fix-bug

Files (3)

• SKILL.md
• git-bisect.md · references/
• regression-hunt.md · references/

SKILL.md (first lines)

> **Tool mapping (OpenCode):** This skill uses:
> - `question` tool for user prompts (not `AskUserQuestion`)
> - `task` tool for subagents (not `Agent` or `Task` subagent syntax)
> - `skill({ name: "..." })` to load other skills (not `Skill(skill="...", args="...")`)
> - `codegraph_explore`, `codegraph_search`, `codegraph_context` for codebase exploration (preferred)
> - `todowrite` for phase/progress tracking
> - `grep`, `glob`, `read`, `bash` as fallback when `.codegraph/` not initialized
>
> **Context rule:** This skill supersedes any prior skill instructions. Follow ONLY these instructions now. Read the user's goal and any mode/include/skip from the conversation context.

> **Mode handling:** Parse `mode=` from the user's message before executing the workflow. Default to `balanced` when no mode is specified. Apply `include=` / `skip=` overrides after mode selection to add or remove workflow steps.

# fix-bug

Diagnose silent integration failures — code that runs without error but the expected side effect never happens. The bug is almost always in the seams: a hook that wasn't loaded, an env var that wasn't injected, a fail-soft `|| true` that swallowed the real error, a shell-quoting mistake, a stale process.

The user has already done the hard part — they noticed the absence. Don't make them ask follow-up questions to extract information you could have given upfront.

---

## When NOT to run

The description covers when to activate. The non-obvious filter:

**Do NOT run** when the failure already has a concrete error message, stack trace, or failing test — those have evidence; this skill is for the *no evidence* case where the side effect silently failed to occur.

**Auto-switch to `mode=regression`** when the user reports that this used to work and recently broke with a named time/version anchor — "worked yesterday", "worked in v1.4", "broken since the deploy", "worked before the auth refactor". Git history is faster than runtime tracing when there's a known-good past. If the user cannot name a past-working anchor, stay in the default workflow — it's a debugging task, not a regression hunt.

---

## Modes

This skill accepts a `mode=` argument. Default — when no `mode=` is specified — is `balanced`: the full 7-step workflow below.

| Mode | Behavior |
|---|---|
| `fast` | Skip the full "Response shape for first message" structure. Trace, identify, patch. For known-cause bugs where the user has already named the suspected line, or trivial single-file fixes. |
| `balanced` (default) | Full 7-step workflow: trace → runtime contract → silent-failure grep → single diagnostic → ranked hypotheses → read evidence literally → propose fix. |
| `production` | `balanced` + after Step 7 (propose fix), invoke `skill({ name: "add-regression-test" })` to pin the bug with a test that fails on the pre-fix code and passes on the post-fix code. |
| `regression` | Load [`references/regression-hunt.md`](references/regression-hunt.md) and follow its phased workflow (confirm anchor → clean tree → repro → log/blame → bisect → root cause). For the bisect phase, read [`references/git-bisect.md`](references/git-bisect.md) for the manual walkthrough (good/bad/skip protocol, merge commits, recovery). Skip fix-bug's default workflow entirely — regression hunting works through git history, not runtime tracing. Stops at root-cause identification; user decides whether to revert, patch, or refactor. |

**`include=` / `skip=` overrides.** Add or remove specific steps — `mode=fast include=regression-test` runs the lean trace + adds a regression test; `mode=production skip=regression-test` runs the full diagnostic without pinning.

**Mode safety override.** If `mode=fast` is requested for a bug touching auth, payments, secrets, schema integrity, or external webhooks, surface the conflict via the `question` tool and confirm before honoring. Silent integration failures in those areas often have second-order causes the runtime contract surfaces — `mode=fast` skips that surfacing.

**Phase-gated NEVER scope.** When `mode=fast` is in effect, *"NEVER list hypotheses without first stating the runtime contract"* is suspended for that run — fast mode explicitly opts out of the contract-first structure. The remaining NEVERs (no overconfident assertion, no parallel-hypothesis test asks, no theorizing past pasted evidence, no ignoring silent-failure patterns, no assuming the running process has latest code) stay in force in every mode.

---

## Workflow

### Step 1 — Trace the integration end-to-end with file:line refs

> **`todowrite`**: Create a todo for "Trace integration end-to-end" (status: `in_progress`). Mark complete when all 4 links are mapped.

Before forming hypotheses, map the *actual* runtime path. **Strongly prefer dispatching a subagent** via `task({ subagent_type: "general", description: "Trace runtime contract", prompt: "For the following integration, trace the runtime path: ..." })` with the integration description — it returns the 4-link trace plus silent-failure sites in a fresh context, which keeps the parent's window clean for hypothesis formation. Use the inline guidance below only when running the trace inline is genuinely faster (single-file integration, you already have the file:line refs from prior turns).

**Prefer `codegraph_explore` for structural trace questions** (file-level symbols, call graphs, type relationships) over grep. Use `grep` only for literal text patterns (error messages, string constants, log lines). When searching for functions by name, use `codegraph_search`.

The trace must cover:

1. Where the side effect is **triggered** (the user's action → handler).
2. Where the side effect is **dispatched** (the outbound call: HTTP, IPC, queue, file write, env injection).
3. Where the side effect is **received** (server handler, listener, hook target).
4. Where the side effect is **observed** (DB row, UI status, log line).

Use Explore/grep/`codegraph_explore` liberally; cite each link with `file:line`. If any link is missing — that's the bug, stop.

**Library boundary as a seam.** If a third-party library mediates any step (terminal emulator, parser, framework router, RPC client, ORM), treat the library as part of the seam. Name the exact entry point you call (e.g. `term.attachCustomKeyEventHandler`) and the exact behavior you assume (e.g. `returning false stops further processing`). Assumed library behavior is a hypothesis until verified against the library's source — not its README, not a code comment, not prior memory (see NEVER #7 below).

**State store as a seam.** If the integration boundary is a stack-specific state layer (a React reducer/context, Redux/Zustand store, Vue reactivity, SwiftUI `@State`, etc.), it is its own seam — with its own update mechanics that can drop or delay messages (lazy updaters, batching, stale closures, double-invocation in dev modes). Don't treat the store as a verified link just because it "ran" — verify the actual stored value after the update, not just that the dispatch fired.

### Step 2 — Surface the runtime contract UPFRONT

> **`todowrite`**: Create a todo for "Surface runtime contract" (status: `pending`). Mark `in_progress` before assembling the contract, mark `completed` when all 6 items are included in the response.

In your **first** response to the user, include all of these without being asked:

- **Exact endpoint(s) hit** — full URL template with substitutions, e.g. `POST http://127.0.0.1:<port>/api/hooks/open-code?taskId=<id>`.
- **Auth shape** — header name, where the token comes from (`Bearer ${apiToken}` from settings DB at `…`).
- **Required env vars** — name, where injected (`MC_TASK_ID`, `MC_API_URL`, `MC_API_TOKEN` injected at `pty-manager.ts:106-108`).
- **On-disk artifacts** — config files written, where (`<cwd>/.opencode/settings.local.json`).
- **Log/observation locations** — where output goes, or "no logs — errors are swallowed at `file:line`".
- **The exact event name / payload shape** the system expects (`hook_event_name: "UserPromptSubmit"`).

**Rule of thumb:** if the user could plausibly ask "what endpoint?" / "what env var?" / "where is it written?" — you failed Step 2. Put it in the first message.

### Step 3 — Identify silent failure points

> **`todowrite`**: Create a todo for "Identify silent failure points" (status: `pending`). Mark `in_progress` before running the grep, mark `completed` when all swallow sites are listed with file:line refs.

Grep the dispatch path for swallowing patterns and call them out explicitly:

```
Use the `grep` tool (or `bash` with `rg -n`) to search the dispatch path:

grep pattern: `\|\| true|catch\s*\{\s*\}|\.catch\(\s*\(\s*\)?\s*=>\s*(undefined|null|void)`
grep pattern: `>/dev/null 2>&1|2>/dev/null`
```

For each hit, note: *"errors here are silently dropped — the only way to know if it ran is to instrument it."* This is almost always where the bug is hiding.

### Step 4 — Ask for the ONE piece of runtime evidence that disambiguates

> **`todowrite`**: Create a todo for "Request disambiguating evidence" (status: `pending`). Mark `in_progress` while selecting the diagnostic, mark `completed` when the user's evidence arrives and is processed.

Don't present 3 hypotheses and ask the user to test all of them. Pick the **single observation** that splits the hypothesis space in half, and ask for it.

**Before picking, ask yourself:** *"Which single observation, if I had it right now, would let me discard the most hypotheses?"* That's the diagnostic to request — not the easiest, not the most familiar, the most disambiguating.

| Integration type | Symptom keywords | Fastest diagnostic |
|------------------|------------------|--------------------|
| HTTP / webhook | "endpoint silent", "callback never came", "POST didn't arrive" | Tail the receiver log while user repros — does the request arrive at all? |
| OpenCode hook | "hook didn't fire", "/hooks" | Run `/hooks` in the OpenCode session — it prints execution errors verbatim (note: `/hooks` may not be available in all OpenCode installations; fall back to checking shell or plugin logs) |
| Env-var injection | "empty value", "command not found in subprocess" | In the spawned shell: `echo "$VAR1\|$VAR2\|$VAR3"` — empty fields = injection failed |
| Config file write | "settings missing", "config not picked up" | Does `<path>` exist? `cat` it. Diff against expected shape. |
| Queue / job worker | "job never ran", "task stuck queued" | Is the worker process alive? Tail its log. Inspect the queue depth/dead-letter. |
| Cron / scheduled | "didn't run at <time>" | Check the scheduler's log for a fire entry; verify the schedule expression and timezone. |
| File watcher | "save didn't trigger rebuild" | `lsof` or platform-specific watcher list — is the path actually being watched? |

From Acauhi99/opencode-agent-system, MIT.

More from Acauhi99/opencode-agent-system