Fix Bug

Fix Bug

Take a bug — described in any form the user has at hand — and either ship a verified draft PR with the fix or hand back a clear, evidence-backed proposal. This skill is a thin orchestrator: heavy reasoning lives in holistic-analysis (dispatched isolated via the rca-investigator agent on the complex lane), gating in confidence, test authoring in /tdd / /e2e-testing / /e2e-testing-mobile, plan authoring in aw-planner (standard-lane) or aw-create-plan (fast-lane), implementation in aw-executor, and independent grading in bug-fix-verifier. This skill owns input classification, complexity triage, evidence assembly, the user-facing decision at the confidence boundary, lane selection, and a durable bug-notes ledger that survives compaction.

> Source of truth. This SKILL.md is a thin index. Detailed procedures live in rules/*.md, > literal artefacts in templates/*.md, and external references in references/*.md. Load only > what the current phase asks for.

Architecture

Phase 0:   Intake                     → classify input + infer bugClass + detect mode flags
Phase 0.5: Complexity Triage          → simple | complex (signals + decision rule)
Phase 1:   Evidence Resolution        → per-input resolution + pre-flight sweep (may upgrade triage)
Phase 2:   Source Mapping + Repro Lock → Evidence Record + failing repro (via /tdd or /e2e-testing*)
Phase 3:   Analysis                   → Task(rca-investigator) — isolated holistic-analysis + confidence [complex]
                                      OR lightweight in-skill analysis [simple]
Phase 4:   Confidence Gate            → /confidence analysis
Phase 5:   Branch Decision            → >= 92 % auto-implement (no human confirmation);
                                       80–91 % stop with raise-the-score guidance,
                                       force-proceed offered (routes standard-lane);
                                       70–79 % stop, force-proceed flagged NOT recommended;
                                       = 92 %):
             │     /fix-bug → Skill("aw-create-plan", ...) → aw-executor
             │     Round-3 CEGIS failure → fall back to standard-lane via aw-planner.
             └── Standard-lane (complex / downgrade / force-proceed):
                   aw-planner → aw-executor (canonical path).
Phase 7:   Independent Verification   → bug-fix-verifier (fresh context) decides PR undraft
                                       Identical for both lanes.
Phase 8:   Telemetry Verification     → poll originating Dash0 query post-deploy (telemetry inputs)

Cross-cutting: a bug-notes ledger at .agent//bug-notes.md is read on entry and appended on exit by every phase — it survives compaction and prevents re-exploring ruled-out hypotheses. See [rules/bug-notes-ledger.md](./rules/bug-notes-ledger.md).

---

Modes

| Flag | Default | Behaviour | |------|---------|-----------| | (none) | yes | Full pipeline (Phases 0–8). Phase 0.5 triages complexity; Phase 5 dispatches via the fast-lane (simple) or standard-lane (complex) when confidence >= 92 % — no human confirmation required. | | --analyse-only | | Read-only analysis. Phases 0–4 (including Phase 0.5 triage) run as normal; Phase 5 always returns the proposal regardless of confidence; Phases 6–8 are skipped. The read-only analysis primitive for any caller that wants a proposal without a PR. (/batch-linear-tickets does not call this — its Phase 1 dispatches linear-ticket-investigator + holistic-analysis directly.) | | --force-holistic | | Skip Phase 0.5's simple classification — always treat the bug as complex. Forces the complex-lane analysis (Phase 3 Task(rca-investigator), which runs holistic-analysis inside) and the standard-lane in Phase 6, regardless of triage signals. Use when triage's conservative-by-default behaviour is not conservative enough for the user's taste. Mutually exclusive with --analyse-only and --verify-deploy. | | --verify-deploy | | Re-entry path for deferred Phase 8 verification. Skips Phases 1–7 entirely; recovers the Evidence Record from .agent//bug-notes.md for the PR's head branch and runs Phase 8 against the already-shipped fix. See [Verify-deploy short-circuit](#verify-deploy-short-circuit) below. |

Flags are mutually exclusive. They are detected in Phase 0 step 0a and stripped from $ARGUMENTS before any further processing.

---

Prerequisites

| Dependency | Purpose | Required? | |-----------|---------|-----------| | rca-investigator agent ([agents/rca-investigator.md](../../../agents/rca-investigator.md)) | Phase 3 complex-lane root-cause analysis — isolated; returns a Root-Cause Record carrying the confidence(analysis) score | Yes for complex lane | | holistic-analysis skill | Phase 3 analysis protocol — run transitively inside rca-investigator; in-context fallback if the agent is unavailable | Yes | | confidence skill | Phase 4 gate (also used inside holistic-analysis / rca-investigator) | Yes | | /tdd skill | Phase 2.5 reproduction at unit / component layer | Yes for non-best-effort repros | | /e2e-testing skill | Phase 2.5 reproduction at user-flow layer (web) | If web E2E repro | | /e2e-testing-mobile skill | Phase 2.5 reproduction at user-flow layer (Expo / React Native) | If mobile E2E repro | | aw-planner + aw-executor agents (from [autonomous-workflow](../autonomous-workflow/SKILL.md)) | Phase 6 standard-lane implementation; aw-planner also handles fast-lane round-3 fallback | Yes for auto-fix path | | [aw-create-plan](../aw-create-plan/SKILL.md) skill | Phase 6 fast-lane plan.md authoring (substitutes for aw-planner when triage = simple AND confidence ≥ 92 %) | Yes for fast-lane | | bug-fix-verifier agent ([agents/bug-fix-verifier.md](../../../agents/bug-fix-verifier.md)) | Phase 7 independent verification | Yes for auto-fix path | | gh CLI | Draft PR creation by aw-executor; gh pr ready by Phase 7 | Yes for auto-fix path | | gw CLI | Worktree management (planner) | Recommended | | persistent-memory skill | fix-bug-lessons self-improvement loop (read Phase 0.5, write Phase 5/7/8) | Optional — loop skips silently if absent | | video-analyser skill | Resolve video / screen-recording inputs — a direct video input (Phase 0 row 3) or a video attachment flagged on a Linear ticket (Phase 1 Linear route) | If video input or a Linear ticket carries a video | | Dash0 MCP server (mcp__dash0__* or equivalent) | Resolve span / log / web event URLs; Phase 8 polling | If Dash0 input | | Linear MCP (mcp__claude_ai_Linear__*) | Linear-ticket input route via linear-ticket-investigator | If Linear input |

---

Rules

| Rule | When it loads | |------|---------------| | [complexity-triage](./rules/complexity-triage.md) | Phase 0.5 — signal table + decision rule + simple / complex outcome | | [evidence-resolution](./rules/evidence-resolution.md) | Phase 1 step 1a — per-input procedures | | [preflight](./rules/preflight.md) | Phase 1.5 — cheap localisation probes; may upgrade triage to simple | | [reproduction](./rules/reproduction.md) | Phase 2.5 — layer routing + delegation to /tdd / /e2e-testing* | | [autonomous-handoff](./rules/autonomous-handoff.md) | Phase 6 — lane selection + fast-lane / standard-lane dispatch + CEGIS contract | | [fast-lane-plan-contract](./rules/fast-lane-plan-contract.md) | Phase 6 fast-lane only — required plan.md sections when /fix-bug authors plan.md directly via aw-create-plan | | [independent-verification](./rules/independent-verification.md) | Phase 7 — verifier checks (FAILTOPASS, PASSTOPASS, diff sanity, repro integrity) | | [telemetry-verification](./rules/telemetry-verification.md) | Phase 8 — post-deploy polling of the originating telemetry query | | [bug-notes-ledger](./rules/bug-notes-ledger.md) | Cross-cutting — durable artefact written by every phase | | [self-improvement-loop](./rules/self-improvement-loop.md) | Cross-cutting — fix-bug-lessons fast tier (read Phase 0.5 / write Phase 5·7·8) + promotion to diagnose | | [diagnostic-surface](./rules/diagnostic-surface.md) | Consumed by /create-skill diagnose fix-bug — phase model, failure taxonomy, existing-guards table, hard invariants |

Templates

| Template | Used in | |----------|---------| | [bug-fix-pack](./templates/bug-fix-pack.md) | Phase 6 — passed to aw-planner; carries the CEGIS refinement contract | | [bug-notes](./templates/bug-notes.md) | Cross-cutting — initial structure for the ledger artefact |

References

| Reference | Topic | |-----------|-------| | [research-sources](./references/research-sources.md) | Curated 2024–2026 sources behind every technique — Anthropic guidance, SWE-bench, RepairAgent, CEGIS, bisection, telemetry verification, taxonomies, practitioner blogs |

---

Phase 0 — Intake & Classification

Step 0a — Detect mode flags

Scan $ARGUMENTS for any of the three mutually-exclusive mode flags:

| Flag | Action | |------|--------| | --analyse-only (or --analyze-only) | Set ANALYSE_ONLY=true. Continue to step 0b. | | --force-holistic | Set FORCE_HOLISTIC=true. Continue to step 0b. Phase 0.5 will skip its decision and pick complex. | | --verify-deploy | Set VERIFY_DEPLOY_MODE=true and VERIFY_DEPLOY_PR=. Skip steps 0b–0c entirely; follow the [Verify-deploy short-circuit](#verify-deploy-short-circuit) below. |

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 before continuing. Print one mode line if any flag was matched:

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

If no flag matched, do not print a mode line and continue to step 0b.

Step 0b — Classify input shape

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

| # | Input shape | Detection rule | Route | |---|-------------|----------------|-------| | 1 | Dash0 URL | Matches https?://[^/]*dash0\.com/ or contains traceId= / spanId= query parameters | [Dash0 resolution](./rules/evidence-resolution.md#dash0-resolution) | | 2 | Linear ticket URL | Matches https?://linear\.app/.+/issue/ | [Linear input](./rules/evidence-resolution.md#linear-input) | | 3 | Video / screen recording | Path / URL ends in .mp4, .mov, .webm, .avi; or text mentions "screen recording", "video of the bug" | Skill("video-analyser", ""), then loop back with structured findings | | 4 | Code pointer | Matches : or #L | [Code pointer](./rules/evidence-resolution.md#code-pointer) | | 5 | Stack trace | Multi-line input matching at .+ \(.+:\d+:\d+\), File ".+", line \d+, or \s+at\s+\S+:\d+ | [Stack trace](./rules/evidence-resolution.md#stack-trace) | | 6 | Error message | Short block matching Error:, Exception:, Traceback, panic:, TypeError, etc. | [Error message](./rules/evidence-resolution.md#error-message) | | 7 | Free-text symptom | Anything else | [Clarifying questions](#clarifying-questions) |

Step 0c — Infer bug class

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

| Class | Signals | |-------|---------| | null-deref | "Cannot read property of undefined", "NoneType has no attribute", "nil pointer dereference" | | race | "intermittent", "sometimes works", "depends on order", concurrency keywords | | off-by-one | "wrong count", boundary-condition keywords, "first/last item missing" | | contract-mismatch | type errors, schema validation failures, API shape mismatches | | perf | "slow", "timeout", "TBT", "INP", profile-shaped evidence | | config | env-var / feature-flag / deploy-config keywords | | regression | "worked before", "started failing on ", pre-flight produced a last_green_sha | | logic | none of the above match — generic logic bug | | unknown | classification not possible from the evidence |

Append to the Evidence Record under Bug class. The class is passed as a hint to holistic-analysis (Phase 3) and informs strategy selection in aw-planner (Phase 6). 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. Suggested priority: telemetry/trace availability, when the bug started, expected vs actual behaviour. Do not run holistic analysis on free text alone.

Phase 0 → Phase 0.5

After step 0c (bugClass inference), continue directly to Phase 0.5 — Complexity Triage below. 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 (canonical holistic-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 so this skill's own past misfires (triage / repro-layer / analysis) bias the run:

Skill("persistent-memory", "read fix-bug-lessons --tier home")     # skips silently if not installed

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). Record applied lessons in the bug-notes ledger. Full contract: [rules/self-improvement-loop.md](./rules/self-improvement-loop.md#read-lessons-phase-05).

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

| Outcome | Phase 3 | Phase 6 lane (provisional) | |---------|---------|----------------------------| | simple | skip — lightweight in-skill analysis | fast-lane (if confidence ≥ 92 % + non-best-effort repro) | | complex | dispatch Task(rca-investigator) — isolated holistic-analysis + confidence | standard-lane |

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//bug-notes.md does not yet exist, create it from [templates/bug-notes.md](./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](./rules/bug-notes-ledger.md#lifecycle)). Pre-flight (Phase 1.5) may upgrade complex → simple later; never the reverse direction inside a run. --force-holistic short-circuits to complex.

---

Verify-deploy short-circuit

Triggered when VERIFY_DEPLOY_MODE=true from step 0a. The PR has already been merged and (presumably) deployed; the user is asking to run Phase 8 against the already-shipped fix. Skip Phases 1–7 entirely.

1. Resolve the PR's head branch and merge commit:

``bash gh pr view --json headRefName,mergeCommit,labels ``

1. Locate the bug-notes ledger at .agent//bug-notes.md in the current checkout.

The ledger survives worktree cleanup because the autonomous-workflow Phase 7 cleanup copies .agent// into the main checkout before removing a worktree with a pending deferred verification — see the [deferred-verification guard](../autonomous-workflow/rules/phase-7-ci-gate.md#optional-post-merge-cleanup). If missing, fail:

```text No bug-notes ledger found for PR # at .agent//bug-notes.md. /fix-bug --verify-deploy can only verify PRs originally produc

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mthines
• Source: mthines/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.