/opencli-autofix

name: opencli-autofix
description: Automatically fix broken OpenCLI adapters when commands fail. Load this skill when an opencli command fails — it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent.
allowed-tools: Bash(opencli:*), Bash(gh:*), Read, Edit, Write

OpenCLI AutoFix — Automatic Adapter Self-Repair

When an `opencli` command fails because a website changed its DOM, API, or response schema, **automatically diagnose, fix the adapter, and retry** — don't just report the error.

Safety Boundaries

**Before starting any repair, check these hard stops:**

• **`AUTH_REQUIRED`** (exit code 77) — **STOP.** Do not modify code. Tell the user to log into the site in Chrome.
• **`BROWSER_CONNECT`** (exit code 69) — **STOP.** Do not modify code. Tell the user to run `opencli doctor`.
• **CAPTCHA / rate limiting** — **STOP.** Not an adapter issue.

**Scope constraint:**

• **Only modify the file at `adapterSourcePath` in the trace `summary.md` front matter** — this is the authoritative adapter location (may be `clis/<site>/` in repo or `~/.opencli/clis/<site>/` for npm installs)
• **Never modify** `src/`, `extension/`, `tests/`, `package.json`, or `tsconfig.json`

**Retry budget:** Max **3 repair rounds** per failure. If 3 rounds of diagnose → fix → retry don't resolve it, stop and report what was tried.

Prerequisites

opencli doctor    # Verify extension + daemon connectivity

When to Use This Skill

Use when `opencli <site> <command>` fails with repairable errors:

• **SELECTOR** — element not found (DOM changed)
• **EMPTY_RESULT** — no data returned (API response changed)
• **API_ERROR** / **NETWORK** — endpoint moved or broke
• **PAGE_CHANGED** — page structure no longer matches
• **COMMAND_EXEC** — runtime error in adapter logic
• **TIMEOUT** — page loads differently, adapter waits for wrong thing

Before Entering Repair: "Empty" ≠ "Broken"

`EMPTY_RESULT` — and sometimes a structurally-valid `SELECTOR` that returns nothing — is often **not an adapter bug**. Platforms actively degrade results under anti-scrape heuristics, and a "not found" response from the site doesn't mean the content is actually missing. Rule this out **before** committing to a repair round:

• **Retry with an alternative query or entry point.** If `opencli xiaohongshu search "X"` returns 0 but `opencli xiaohongshu search "X 攻略"` returns 20, the adapter is fine — the platform was shaping results for the first query.
• **Spot-check in a normal Chrome tab.** If the data is visible in the user's own browser but the adapter comes back empty, the issue is usually authentication state, rate limiting, or a soft block — not a code bug. The fix is `opencli doctor` / re-login, not editing source.
• **Look for soft 404s.** Sites like xiaohongshu / weibo / douyin return HTTP 200 with an empty payload instead of a real 404 when an item is hidden or deleted. The snapshot will look structurally correct. A retry 2-3 seconds later often distinguishes "temporarily hidden" from "actually gone".
• **"0 results" from a search is an answer.** If the adapter successfully reached the search endpoint, got an HTTP 200, and the platform returned `results: []`, that is a valid answer — report it to the user as "no matches for this query" rather than patching the adapter.

Only proceed to Step 1 if the empty/selector-missing result is **reproducible across retries and alternative entry points**. Otherwise you're patching a working adapter to chase noise, and the patched version will break the next working path.

Step 1: Collect Trace Context

Run the failing command with failure-retained trace enabled:

opencli <site> <command> [args...] --trace retain-on-failure 2>trace-error.yaml

On failure, stderr contains the normal error envelope plus a small `trace` block:

ok: false
error:
  code: SELECTOR
  message: "Could not find element: .old-selector"
trace:
  schemaVersion: 1
  opencliVersion: "..."
  traceId: "..."
  dir: "/path/to/.opencli/profiles/default/traces/..."
  summaryPath: "/path/to/.opencli/profiles/default/traces/.../summary.md"
  receiptPath: "/path/to/.opencli/profiles/default/traces/.../receipt.json"

Read `summaryPath` first. It is the LLM-oriented entry point and includes front matter:

---
schemaVersion: 1
opencliVersion: "..."
traceId: "..."
status: failure
site: "example"
command: "example/search"
adapterSourcePath: "/path/to/clis/example/search.js"
errorCode: "SELECTOR"
errorMessage: "Could not find element: .old-selector"
---

The artifact directory contains:

summary.md      # start here
receipt.json    # machine-readable trace receipt
trace.jsonl     # full redacted timeline
network.jsonl   # redacted network events
console.jsonl   # redacted console events
state/          # final snapshots when available
screenshots/    # final screenshots when available

If you redirected stderr to a file, read that file and copy `trace.summaryPath`.

Do not ask the user to rerun with legacy diagnostic env vars. Trace is the repair evidence path.

Step 2: Analyze the Failure

Read the trace summary and the adapter source. Classify the root cause:

| Error Code | Likely Cause | Repair Strategy | |-----------|-------------|-----------------| | SELECTOR | DOM restructured, class/id renamed | Explore current DOM → find new selector | | EMPTY_RESULT | API response schema changed, or data moved | Check network → find new response path | | API_ERROR | Endpoint URL changed, new params required | Discover new API via network intercept | | AUTH_REQUIRED | Login flow changed, cookies expired | **STOP** — tell user to log in, do not modify code | | TIMEOUT | Page loads differently, spinner/lazy-load | Add/update wait conditions | | PAGE_CHANGED | Major redesign | May need full adapter rewrite |

**Key questions to answer:** 1. What is the adapter trying t