# Fix Bug

> >

- **Type:** Skill
- **Install:** `agentstack add skill-mthines-agent-skills-fix-bug`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mthines](https://agentstack.voostack.com/s/mthines)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mthines](https://github.com/mthines)
- **Source:** https://github.com/mthines/agent-skills/tree/main/skills/workflow/fix-bug

## Install

```sh
agentstack add skill-mthines-agent-skills-fix-bug
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```text
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 (FAIL_TO_PASS, PASS_TO_PASS, 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:

```text
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](https://software-lab.org/publications/icse2025_RepairAgent.pdf)),
[NIST Seven Pernicious Kingdoms](https://samate.nist.gov/SSATTM_Content/papers/Seven%20Pernicious%20Kingdoms%20-%20Taxonomy%20of%20Sw%20Security%20Errors%20-%20Tsipenyuk%20-%20Chess%20-%20McGraw.pdf).

### 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:

```text
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
   ```

2. **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](https://github.com/mthines)
- **Source:** [mthines/agent-skills](https://github.com/mthines/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mthines-agent-skills-fix-bug
- Seller: https://agentstack.voostack.com/s/mthines
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.