Fix Bug

Take a bug in any form and either ship a verified draft PR or hand back an evidence-backed proposal. This skill runs evidence intake, root-cause analysis, and verification itself; gating, repro authoring, planning, and implementation run in the skills and agents each phase names.

Contents

Phases: 0 Intake → 0.5 Triage → 1 Evidence → 2 Repro lock → 3 Analysis → 4 Confidence → 5 Decision → 6 Handoff → 7 Verify → 8 Telemetry; then Lesson writes and Output Format.

The bug-notes ledger at .agent/<branch>/bug-notes.md is read on entry and appended on exit by every phase — rules/bug-notes-ledger.md. Read rules/prerequisites.md when a dependency (agent, skill, CLI, MCP) is missing or may be optional. Read references/design-rationale.md or references/research-sources.md when you need the why behind a gate or threshold.

Phase 0 — Intake & Classification

Step 0a — Detect mode flags

If two or more flags are present, fail with --analyse-only, --force-holistic, and --verify-deploy are mutually exclusive. Strip the matched flag (and its argument, for --verify-deploy) from $ARGUMENTS. Print one mode line only if a flag matched:

Mode: analyse-only
Mode: force-holistic
Mode: verify-deploy (PR #<N>)

Step 0b — Classify input shape

Walk the table top-to-bottom. The first matching row wins.

Step 0c — Infer bug class

Infer a bugClass tag from the symptom and any stack-trace / error-message text. Pick from:

Append to the Evidence Record under Bug class. The class is a hint for the Phase 3 trace and informs strategy selection in the Phase 6 brief. Source: RepairAgent (ICSE 2025), NIST Seven Pernicious Kingdoms.

Clarifying questions

If the input is free text or empty, ask up to 3 questions in one message and wait. Priority: telemetry/trace availability, when the bug started, expected vs actual behaviour. Do not run analysis on free text alone. After step 0c, continue to Phase 0.5; Phase 1 does not start until triage commits.

Phase 0.5 — Complexity Triage

Pick between two routing lanes for the rest of the pipeline: simple (lightweight in-skill analysis + fast-lane handoff) or complex (full execution-path root-cause analysis + standard-lane handoff). This is a routing decision, not a quality decision — confidence (Phase 4) still owns the auto-implement call.

Before the decision — read prior lessons. Load fix-bug-lessons from LoreKit (narrow-to-broad — this repo's scope, then global) so this skill's own past misfires (triage / repro-layer / analysis) bias the run:

memory.list { scope: "repo::{owner}/{repo}", tags: ["loop::fix-bug-lessons"], limit: 50 }   # no-op if memory.* not connected
memory.list { scope: "global", tags: ["loop::fix-bug-lessons"], limit: 50 }

Match lessons by bugClass + input shape; apply matches as advisory inputs to the triage decision (they never override the conservative complex default or relax any gate). Skip lessons whose expires has passed. Record applied lessons in the bug-notes ledger. Full contract: rules/self-improvement-loop.md.

Walk the 14-row signal table in rules/complexity-triage.md and apply the decision rule (conservative default: pick complex when in doubt). The outcome:

Append the classification, signals, decision, and provisional lane to the bug-notes ledger under a Complexity triage section. The ledger is created on first write: if .agent/<branch-or-slug>/bug-notes.md does not yet exist, create it from templates/bug-notes.md before appending — under the normal flow this Phase 0.5 append is the first write and therefore the creation point (see rules/bug-notes-ledger.md). Pre-flight (Phase 1.5) may upgrade complex → simple later; never the reverse direction inside a run. --force-holistic short-circuits to complex.

Phase 1 — Evidence Resolution

Step 1a. Walk only the procedures in rules/evidence-resolution.md that match the Phase 0 inputs; each produces a partial evidence record.

Phase 1.5 — Pre-flight sweep. Run the probes in rules/preflight.md (recent commits to affected files, last-known-green deploy SHA, lockfile / env diff, CI flips) and append findings to the Evidence Record. If pre-flight produces a single-commit short-circuit (commit + diff size + CI flip window all align), skip Phase 3 and route to Phase 5 with a high-confidence proposal. Otherwise capture the regression window for step 2c.

Phase 2 — Source Mapping + Reproduction Lock

Step 2a. Merge the Phase 1 partial records into one Evidence Record (schema: templates/bug-notes.md § Evidence Record).

Phase 2.5 — Reproduction lock. Build a deterministic failing repro per rules/reproduction.md. For a telemetry-sourced input, first run the rule's repro-fidelity check: run the repro locally, then Skill("telemetry-verify", "--env local --from <start> --to <end> --no-comment") over that window with the originating span's shape from the Evidence Record as literal expectations — never as "matches production", since telemetry-verify reads only the local run's window. The check is advisory and never touches Phase 8. Then pick the lowest layer that captures the bug and delegate:

• Unit / component / hook / integration → Skill("tdd", ...)
• Web user flow → Skill("e2e-testing", ...)
• Expo / React Native user flow → Skill("e2e-testing-mobile", ...)
• Visual-only / pixel-perfect → best-effort markdown checklist

The repro is Phase 6's FAIL_TO_PASS contract and Phase 7's FAIL_TO_PASS check. Path convention: repro/<short-bug-id>.<ext>.

Step 2c — Bisect fast-path (regression class only). If pre-flight produced a last_green_sha AND a non-best-effort repro exists, run git bisect run <repro-command>. If the offending commit's diff is ≤ 50 lines, route to Phase 5 with proposal "revert or amend <sha>" (details).

Step 2d. Append the Evidence Record to the ledger, creating it from the template only if no earlier phase did (lifecycle).

Phase 3 — Analysis

complex path — full root-cause analysis

Read rules/root-cause-analysis.md and run it in this context, starting from the Phase 2 Evidence Record, the bugClass hint, any pre-flight or bisect finding, and every ledger hypothesis with state = ruled-out:

1. Trace the execution path from entry to exit across files, recording each hop at file:line.
2. Rule out at least 2 alternative causes, each with concrete evidence.
3. Name the root cause — the earliest hop whose fix makes the symptom impossible, not the symptom hop.
4. Score it with Skill("confidence", "analysis\n\n<conclusion + evidence>"); below 90 %, re-trace the weakest hop once and re-score.
5. Append the Root-Cause Record to the ledger.

simple path — lightweight in-skill analysis

Skip the full trace (what simple skips):

1. Read the suspect file at the suspect line + 30 lines of context.
2. Identify the minimal change that satisfies the failing repro (Phase 2.5) and does not break neighbours.
3. Write a root-cause paragraph to the Evidence Record — same shape as the Root-Cause Record, including a Falsifiable prediction: line that the repro confirms.
4. Continue to Phase 4 — the score comes from the confidence skill, never self-graded.

If the lightweight analysis cannot propose a fix (suspect file not in the failing path, or more than one plausible cause), upgrade triage to complex, run the complex path, and log triage upgrade: simple → complex (lightweight analysis under-determined).

Phase 4 — Confidence Gate

Reuse the Phase 3 score from the Root-Cause Record. Re-run /confidence analysis only if new evidence arrived since Phase 3 or the proposed fix materially changed. Append the score and breakdown to the ledger's Confidence trajectory table.

Phase 5 — Branch Decision

Step 5a — Reproduction gate (mechanical)

Runs before the confidence action, regardless of score and of ANALYSE_ONLY; there is no force-proceed below it. Read .agent/<branch-or-slug>/bug-notes.md § ## Reproduction (Phase 2.5) and extract Path:, Status:, and (when present) Reason:.

If neither holds, emit the Step 5a error verbatim and return to Phase 2.5.

Step 5b — Confidence-based action

If ANALYSE_ONLY=true, always return the proposal (after Step 5a passes), skip Phases 6–8, and set Outcome to analyse-only (no PR).

Otherwise:

On a stop (< 92 %), a triage upgrade (simple → complex), or a fast-lane → standard-lane CEGIS fallback, write a lesson with trigger phase-5-stop (Lesson writes).

Phase 6 — Autonomous Handoff (Lane-Split)

Runs only when ANALYSE_ONLY is unset and Phase 5 cleared at >= 92 % (or the user force-proceeded at 70–91 %, which forces the standard-lane).

Step 6.pre — Branch pre-flight assertion (mechanical)

Before lane selection, run git rev-parse --abbrev-ref HEAD. If the result is in the closed protected-branch list {main, master, develop, trunk}, emit the Step 6.pre error and refuse to proceed; the agent must run gw checkout fix/<slug> (step 6a) before re-entering Phase 6. Any other branch continues.

Step 6.main — Lane selection and dispatch

Follow rules/autonomous-handoff.md (fast-lane plan.md: rules/fast-lane-plan-contract.md; standard-lane pack: templates/bug-fix-pack.md). Both lanes share the CEGIS 3-round cap; a fast-lane round-3 failure falls back to the standard-lane with the captured counterexamples.

Implementation runs in this session, in the fix/<slug> worktree, never on a protected branch (Step 6b): you hold the repro and the root cause, so you write the fix, branch-reviewer reviews it, and feature-pr-verifier checks the draft PR. Dispatch aw-executor only when the user asks for a background worker. Step 7.pre fails closed when no draft PR exists.

Phase 7 — Verification

Step 7.pre — Draft PR assertion (mechanical)

Run gh pr view --json url,isDraft,headRefName 2>/dev/null for the current branch. All must hold: a PR exists (exit 0 with JSON, not the MISSING fallback); isDraft = true; headRefName equals git rev-parse --abbrev-ref HEAD. On pass, capture the PR URL. On any failure, emit the Step 7.pre error and stop — there is no force-proceed, and skipping verification for a "small diff" is forbidden.

Step 7.main — Run the four checks

Read rules/independent-verification.md and run, in this context, against the repro, the diff, and the Evidence Record (not plan.md): FAIL_TO_PASS (the repro fails on base and passes on the PR head), PASS_TO_PASS (no previously passing test fails), diff sanity (no catch-all swallows, debug statements, deleted tests, or .skip / .only), and repro integrity (the repro was not weakened). Write the verdict and evidence into the PR body's ## Verification section. /fix-bug never undrafts: on green and on red the PR stays draft for a human to review and run gh pr ready. On a RED, write a lesson with trigger verifier-red, naming which earlier phase under-caught it (triage too simple? repro false-green? analysis wrong file?).

Phase 8 — Telemetry Verification

Runs only for a Dash0 / telemetry input once the PR is merged and deployed; the fix is done when the originating signal stops firing. Classify the bug's observability shape (Step 8a) and pick one of five modes (Step 8b) — rate-decay, extended watch, cohort absence, build-version absence, or deferred-watch — then run it, all per rules/telemetry-verification.md. Default operating mode is deferred: emit a follow-up task to re-invoke /fix-bug --verify-deploy <PR> once the deploy lands. --inline-verify runs synchronously when the project auto-deploys on merge. If the originating signal does not decay (or recurs), write a lesson with trigger telemetry-firing.

Lesson writes

Fast tier: LoreKit fix-bug-lessons (tag loop::fix-bug-lessons), read at Phase 0.5 and written at the triggers below, per rules/self-improvement-loop.md § Write lessons (scope classification, memory.search dedup, then memory.write with key fix-bug-lessons::<slug>, tags ["loop::fix-bug-lessons", "source::<trigger>"], source_agent: "fix-bug", trigger: "<trigger>"). A silent no-op when memory.* is not connected; the write skips consent, not the privacy pre-flight. Implementation-phase lessons live in aw-lessons, not here.

Slow tier: if a run shipped wrong code despite all three confidence gates, a post-merge regression traces to a missed check, or a lesson recurs seen_count >= 3, invoke /create-skill diagnose fix-bug while the failing session is still in context; it reads rules/diagnostic-surface.md.

Output Format

For every Phase 5 outcome, including --analyse-only, print the ## Fix-bug summary block in rules/output-format.md (Evidence, Triage, Reproduction, Root cause, Proposed change, Confidence, Outcome).