fix-bug

name	fix-bug
description	Resolves a single bug from any starting evidence — Dash0 telemetry (span / log / web event / RUM error link), raw stack trace, error message, code pointer (file:line), screen recording, Linear ticket URL, or free-text symptom. Classifies the input, **triages complexity** (Phase 0.5) to pick between a fast lane and a full holistic-analysis lane, runs a pre-flight sweep, locks a failing reproduction (delegating to /tdd, /e2e-testing, or /e2e-testing-mobile by layer), delegates root-cause analysis to the isolated rca-investigator agent (holistic-analysis + confidence) on complex bugs (or runs a lightweight in-skill analysis on simple ones), gates on confidence(analysis), and on >= 92 % hands off **without human confirmation**: simple bugs take the fast lane (/fix-bug → aw-create-plan → aw-executor, no aw-planner) and complex bugs take the standard lane (aw-planner → aw-executor), both with a CEGIS refinement contract. Fast-lane round-3 CEGIS failure falls back to standard-lane via aw-planner. An independent bug-fix-verifier agent grades the PR before undrafting; for telemetry-sourced bugs an optional Phase 8 polls the originating signal post-deploy. Pass --analyse-only to stop after the proposal regardless of confidence; --force-holistic to skip the fast lane and always use holistic-analysis. Triggers on "fix this bug", "investigate this error", "this Dash0 span shows a failure", "this stack trace looks wrong", "/fix-bug".
argument-hint	[--analyse-only|--force-holistic] [<bug-description>|<ticket>]
license	MIT
user-invocable	true
disable-model-invocation	false
metadata	{"author":"mthines","version":"2.3.0","workflow_type":"orchestrator","architecture":"classify/triage/preflight/reproduce/analyse/gate/handoff(fast|standard)/verify/telemetry","agents":{"rca":"rca-investigator","planner":"aw-planner","executor":"aw-executor","verifier":"bug-fix-verifier","investigator":"linear-ticket-investigator"},"composes":["holistic-analysis","confidence","aw-create-plan","tdd","e2e-testing","e2e-testing-mobile","video-analyser","autonomous-workflow"],"phases":["intake","complexity_triage","evidence_resolution_with_preflight","source_mapping_with_reproduction","holistic_analysis_or_lightweight","confidence_gate","branch_decision","autonomous_handoff_lane_split","independent_verification","telemetry_verification"],"tags":["bug-fix","debugging","telemetry","dash0","confidence-gated","reproduction-first","cegis","autonomous-workflow","root-cause","orchestrator","complexity-triage","fast-lane"]}

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;
                                       < 70 % stop, no force-proceed.
                                       --analyse-only always stops here.
Phase 6:   Autonomous Handoff (lane-split)
             ├── Fast-lane (simple + >= 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/<branch>/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.

---

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 <PR>		Re-entry path for deferred Phase 8 verification. Skips Phases 1–7 entirely; recovers the Evidence Record from .agent/<branch>/bug-notes.md for the PR's head branch and runs Phase 8 against the already-shipped fix. See 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)	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)	Phase 6 standard-lane implementation; aw-planner also handles fast-lane round-3 fallback	Yes for auto-fix path
aw-create-plan 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)	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
lorekit-memory skill (LoreKit memory.* tools)	fix-bug-lessons self-improvement loop (read Phase 0.5, write Phase 5/7/8)	Optional — loop is a silent no-op if memory.* is not connected
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	Phase 0.5 — signal table + decision rule + simple / complex outcome
evidence-resolution	Phase 1 step 1a — per-input procedures
preflight	Phase 1.5 — cheap localisation probes; may upgrade triage to simple
reproduction	Phase 2.5 — layer routing + delegation to /tdd / /e2e-testing*
autonomous-handoff	Phase 6 — lane selection + fast-lane / standard-lane dispatch + CEGIS contract
fast-lane-plan-contract	Phase 6 fast-lane only — required plan.md sections when /fix-bug authors plan.md directly via aw-create-plan
independent-verification	Phase 7 — verifier checks (FAIL_TO_PASS, PASS_TO_PASS, diff sanity, repro integrity)
telemetry-verification	Phase 8 — post-deploy polling of the originating telemetry query
bug-notes-ledger	Cross-cutting — durable artefact written by every phase
self-improvement-loop	Cross-cutting — fix-bug-lessons fast tier (read Phase 0.5 / write Phase 5·7·8) + promotion to diagnose
diagnostic-surface	Consumed by /create-skill diagnose fix-bug — phase model, failure taxonomy, existing-guards table, hard invariants

Templates

Template	Used in
bug-fix-pack	Phase 6 — passed to aw-planner; carries the CEGIS refinement contract
bug-notes	Cross-cutting — initial structure for the ledger artefact

References

Reference	Topic
research-sources	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 <PR>	Set VERIFY_DEPLOY_MODE=true and VERIFY_DEPLOY_PR=<PR>. Skip steps 0b–0c entirely; follow the 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 #<N>)

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
2	Linear ticket URL	Matches https?://linear\.app/.+/issue/	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", "<input>"), then loop back with structured findings
4	Code pointer	Matches <path>:<line> or <path>#L<line>	Code pointer
5	Stack trace	Multi-line input matching at .+ \(.+:\d+:\d+\), File ".+", line \d+, or \s+at\s+\S+:\d+	Stack trace
6	Error message	Short block matching Error:, Exception:, Traceback, panic:, TypeError, etc.	Error message
7	Free-text symptom	Anything else	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 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:

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/<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.

---

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:

   gh pr view <PR> --json headRefName,mergeCommit,labels
   

2. Locate the bug-notes ledger at .agent/<headRefName>/bug-notes.md in the current checkout. The ledger survives worktree cleanup because the autonomous-workflow Phase 7 cleanup copies .agent/<branch>/ into the main checkout before removing a worktree with a pending deferred verification — see the deferred-verification guard. If missing, fail:

   No bug-notes ledger found for PR #<N> at .agent/<branch>/bug-notes.md.
   /fix-bug --verify-deploy can only verify PRs originally produced by /fix-bug —
   the ledger is the recovery handle for post-deploy verification.
   

3. Read the ledger. Recover the originating telemetry source from the Evidence Record's Sources section, the pre-fix baseline from the Phase 8 shape (or recompute via the originating query), and the deploy ID from PR labels or the merge commit's service.version annotation.

4. Validate input was telemetry-sourced. If the Evidence Record's Sources field does not contain a Dash0 / telemetry URL, fail:

   PR #<N> was not opened from a telemetry-sourced bug. /fix-bug --verify-deploy
   only applies to bugs whose original input was a Dash0 / telemetry URL.
   

5. Jump to Phase 8 step 8a (classify shape) with the recovered Evidence Record. Phase 8 then proceeds normally — classify, pick a verification mode, and run the chosen mode.

6. After Phase 8 completes, append the result to the ledger under Phase log and post a comment on the PR (and the originating Linear ticket if the input carried one). Exit.

---

Phase 1 — Evidence Resolution

Step 1a — Per-input resolution

Walk only the procedures in rules/evidence-resolution.md that match the inputs classified in Phase 0. Each procedure produces a partial evidence record.

Phase 1.5 — Pre-flight sweep

Run the deterministic localisation probes in rules/preflight.md — recent commits to affected files, last-known-green deploy SHA, lockfile / env diff, CI flips. 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 directly to Phase 5 with a high-confidence proposal. Otherwise capture the regression window for the step 2c bisect fast-path.

---

Phase 2 — Source Mapping + Reproduction Lock

Step 2a — Build the Evidence Record

Merge the partial records from Phase 1 into a single Evidence Record. The schema lives in templates/bug-notes.md under the Evidence Record section. This is the input to Phase 3 and the seed for the bug-notes ledger.

Phase 2.5 — Reproduction lock

Construct a deterministic failing reproduction following rules/reproduction.md. The rule's layer-routing table picks the lowest test layer that can capture the bug, then delegates:

• 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 the executor's FAIL_TO_PASS contract (Phase 6) and the verifier's FAIL_TO_PASS check (Phase 7). The path convention is repro/<short-bug-id>.<ext>.

Step 2c — Bisect fast-path (regression class only)

If the pre-flight sweep 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>". See reproduction.md → Bisect fast-path.

Step 2d — Seed the Evidence Record into the bug-notes ledger

The ledger at .agent/<branch-or-slug>/bug-notes.md normally already exists — it is created on first write, which under the normal flow is the Phase 0.5 triage append. Create it from templates/bug-notes.md now only if no earlier phase wrote it (create-if-missing). Append the merged Evidence Record from step 2a. Every later phase reads on entry and appends on exit. See rules/bug-notes-ledger.md.

---

Phase 3 — Analysis

The phase splits by triage outcome (Phase 0.5):

Phase 3 — complex path: Holistic Analysis (isolated)

Dispatch the rca-investigator agent with the Evidence Record (including the bugClass hint and any pre-flight short-circuit findings):

Task(subagent_type="rca-investigator", prompt="<Evidence Record from Phase 2>")

The agent runs holistic-analysis in fix mode + /confidence analysis in its own context and returns a compact Root-Cause Record (root cause, causal chain, evidence, ruled-out alternatives, confidence score, fix direction). The verbose 8-phase walkthrough stays inside the agent and never pollutes this orchestrator's window — only the distilled record comes back. This is a single dispatch (one bug, nothing to parallelize); the win here is isolation, not parallelism.

Do not re-run the analysis or the confidence score here — both are in the returned record.

If the bug-notes ledger has any state = ruled-out hypotheses, pass them in the prompt so the agent does not re-explore them.

If the rca-investigator agent is unavailable in the host project, fall back to running Skill("holistic-analysis", "fix\n\n<Evidence Record>") in-context (it internally calls /confidence analysis at its Phase 6) — the same analysis, without the isolation benefit.

Phase 3 — simple path: Lightweight in-skill analysis

Skip holistic-analysis entirely. Run the lightweight procedure described in rules/complexity-triage.md:

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 holistic-analysis produces, including a Falsifiable prediction: line that the repro confirms.
4. Continue to Phase 4 (confidence gate) — the score is still emitted by the confidence skill, never self-graded.

If the lightweight analysis cannot propose a fix (suspect file isn't actually in the failing path, predicate has more than one plausible cause), upgrade triage to complex and run holistic-analysis after all. Log the upgrade in the ledger as triage upgrade: simple → complex (lightweight analysis under-determined).

---

Phase 4 — Confidence Gate

Reuse the score from Phase 3 — the rca-investigator Root-Cause Record carries it (or, on the in-context fallback, the score holistic-analysis emitted at its Phase 6). Re-run /confidence analysis here only if new evidence has arrived between Phase 3 and now, or the proposed fix has materially changed.

Append the score and breakdown to the bug-notes ledger's Confidence trajectory table.

---

Phase 5 — Branch Decision

Step 5a — Reproduction gate (mechanical)

Before evaluating the confidence-based action below, the skill must validate that Phase 2.5 actually produced a usable reproduction artefact. This is a deterministic check on the bug-notes ledger; it runs regardless of confidence score and regardless of ANALYSE_ONLY. There is no force-proceed below this gate — the repro is the executor's FAIL_TO_PASS contract (Phase 6) and the verifier's primary check (Phase 7), and analyse-only consumers need it to be a useful proposal.

Procedure:

1. Read .agent/<branch-or-slug>/bug-notes.md.
2. Locate the ## Reproduction (Phase 2.5) section.
3. Extract the Path:, Status:, and (when present) Reason: fields.
4. Apply the pass conditions:

#	Pass condition
1	Path: resolves to an existing file matching the project's test convention (e.g. repro/*.test.{ts,tsx,js,jsx,mjs}, repro/test_*.py, repro/*_test.go, repro/*.rs) AND Status: contains failing on HEAD as expected
2	Path: resolves to an existing repro/*.md file AND Status: contains best-effort AND Reason: is one of: race, production-only, heisenbug, visual, performance

If neither condition holds, fail with this exact structured error and route back to Phase 2.5:

Phase 5 gate failed: Phase 2.5 did not produce a gate-eligible reproduction.

Bug-notes ledger says:
  Path:   <verbatim from ledger or "missing">
  Status: <verbatim from ledger or "missing">
  Reason: <verbatim from ledger or "missing">

A reproduction must satisfy one of:
  1. Runnable test at repro/<id>.<test-ext> with Status "failing on HEAD as expected"
  2. Best-effort marker at repro/<id>.md with Status "best-effort" AND
     Reason in {race, production-only, heisenbug, visual, performance}

Returning to Phase 2.5. Re-invoke /tdd, /e2e-testing, or /e2e-testing-mobile,
or explicitly document a best-effort reason from the closed list above.
The forbidden self-justifications ("small diff", "pattern exercised elsewhere",
"scaffolding overhead", "would duplicate the fix") are not valid reasons —
see rules/reproduction.md § Forbidden reasons to skip Phase 2.5.

There is no force-proceed below this gate.

The closed list of best-effort reasons is taken verbatim from rules/reproduction.md: race, production-only, and heisenbug from Best-effort fallback; visual and performance from rows 7–8 of the layer routing table. The gate widens only when the spec widens — never inline.

Step 5b — Confidence-based action

If ANALYSE_ONLY=true, always return the proposal regardless of confidence (Step 5a must have passed first). Skip Phases 6–8. The output's Outcome line indicates analyse-only (no PR). Triage classification is included in the output for reference but does not affect behaviour in this mode.

Otherwise:

Confidence	Action
>= 92%	Fully autonomous — no human confirmation required. Print a one-line status (lane + root cause + score) and proceed directly to Phase 6. Lane is fast-lane if Phase 0.5 triage = simple AND a non-best-effort repro exists; otherwise standard-lane.
80–91%	Stop. Present Evidence Record + proposed fix + confidence breakdown + what would raise the score. Offer: collect more evidence, force-proceed, or abandon. Force-proceed at this tier always routes to the standard-lane (planner's confidence(plan) gate is the extra safety net when analysis confidence is marginal).
70–79%	Stop. Force-proceed offered but flagged NOT recommended. Same standard-lane routing as 80–91 % when force-proceed is taken.
< 70%	Stop. Do NOT offer force-proceed. Present analysis findings (holistic or lightweight) as a discussion document. Ask the user for direction. Hard invariant — no escape hatch.

The 92 % threshold is the substitute for aw-planner's confidence(plan) ≥ 90 % that the fast-lane bypasses. It is stricter on purpose: bypassing the planner means one fewer independent gate, and the higher bar on the gate we keep restores the three-gate invariant.

On a stop (< 92 %, or below-70 % hand-back), and on any triage upgrade (simple → complex) or fast-lane → standard-lane CEGIS fallback, write a lesson so the next bug of this bugClass does better — classify scope (universal → global; project-bound → repo::{owner}/{repo}), dedup, then write:

memory.search { q: "<lesson keywords>", scopes: ["repo::{owner}/{repo}", "global"], limit: 10 }     # no-op if memory.* not connected
memory.write { scope: "<global | repo::{owner}/{repo}>", key: "fix-bug-lessons::<slug>", value: "<body>", tags: ["loop::fix-bug-lessons", "source::phase-5-stop"], source_agent: "fix-bug", trigger: "phase-5-stop" }

The write skips consent, not the privacy pre-flight. See rules/self-improvement-loop.md.

---

Phase 6 — Autonomous Handoff (Lane-Split)

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

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

Before any lane selection or dispatch, validate that the current working branch is not a protected trunk branch. This catches the case where Phase 1–5 happened to run on main and the agent is about to start implementation work without first creating a worktree.

Procedure:

1. Run git rev-parse --abbrev-ref HEAD.
2. If the result is in the closed protected-branch list {main, master, develop, trunk}, fail-closed with the structured error below and refuse to proceed. The agent must run gw checkout fix/<slug> (see rules/autonomous-handoff.md) before re-entering Phase 6.
3. If the result is anything else (e.g. fix/*, feat/*, an existing feature branch), continue to lane selection.

Structured error on fail:

Phase 6 gate failed: working on protected branch `<branch>`.

Phase 6 implementation work happens inside an isolated worktree on a fix/* branch,
dispatched via `aw-executor` (which opens a draft PR). Editing files inline on a
protected trunk branch bypasses:
  - worktree isolation
  - draft PR creation
  - bug-fix-verifier (Phase 7) fresh-context grading

Run `gw checkout fix/<slug>` first, then re-enter Phase 6. There is no force-proceed
below this gate — committing implementation work directly to a protected branch is
forbidden by hard invariant in rules/diagnostic-surface.md.

The protected-branch list is conservative: it matches industry default trunk conventions and does not match private feature branches. If a project uses a non-standard trunk name, extend the closed list in SKILL.md Phase 6 — never inline.

Step 6.main — Lane selection and dispatch

Lane is picked from triage + fast-lane preconditions:

Lane	Trigger	Plan authored by
Fast-lane	triage = simple AND confidence ≥ 92 % AND non-best-effort repro	/fix-bug → Skill("aw-create-plan", ...) (no aw-planner)
Standard-lane	complex / downgrade / force-proceed	aw-planner (canonical)

On fast-lane, round-3 CEGIS failure falls back to standard-lane via aw-planner with the captured counterexamples — single-shot safety net.

Full procedure: rules/autonomous-handoff.md. Fast-lane plan.md shape: rules/fast-lane-plan-contract.md. Standard-lane pack: templates/bug-fix-pack.md. Phase 7 (verifier) and the CEGIS 3-round cap are identical for both lanes; only the round-3 escalation path differs.

The main agent does not execute file edits inline in Phase 6. All implementation work runs inside the aw-executor subagent via Task(subagent_type="aw-executor", ...). The Step 7.pre gate fails-closed when no draft PR exists for the current branch, catching the case where the main agent bypassed dispatch and edited files directly.

---

Phase 7 — Independent Verification

Step 7.pre — Draft PR assertion (mechanical)

Before spawning bug-fix-verifier, validate that Phase 6 actually produced a draft PR. This catches the case where the main agent bypassed Phase 6 dispatch entirely (no Task(subagent_type="aw-executor", ...) invocation, inline edits on a working branch, or direct commit / push to a protected branch).

Procedure:

1. Run gh pr view --json url,isDraft,headRefName 2>/dev/null for the current branch.
2. Pass conditions, all must hold:
   • A PR exists (gh pr view exits 0 and returns JSON, not the MISSING fallback).
   • isDraft = true.
   • headRefName matches the current branch from git rev-parse --abbrev-ref HEAD.
3. On pass, capture the PR URL and proceed to the verifier spawn below.
4. On any failure, fail-closed with the structured error below. There is no force-proceed below this gate — the verifier cannot grade a PR that does not exist, and skipping the verifier on the grounds of "small diff" is forbidden by hard invariant.

Structured error on fail:

Phase 7 gate failed: no draft PR exists for branch `<branch>`.

`gh pr view` returned: <verbatim output or "MISSING">

Phase 6 dispatch must produce a draft PR via `Task(subagent_type="aw-executor", ...)`.
If you find that:
  - You are still on a protected branch (main / master / develop / trunk)
  - Implementation files were edited inline by the main agent
  - `git log` shows implementation commits already on a protected branch
…then Phase 6 was bypassed. The bug-fix-verifier cannot run in this state.

Recovery:
  1. Revert / cherry-pick the implementation off the protected branch (manual — destructive).
  2. Run `gw checkout fix/<slug>` to create the worktree.
  3. Re-enter Phase 6 via the documented dispatch path (Step 6.main).
  4. Phase 7 will re-run once aw-executor produces the draft PR.

Skipping the verifier on the grounds of "diff is small", "pattern matches existing code",
or "verifier exists for diff-sanity grading only" is forbidden — see
rules/diagnostic-surface.md hard invariants.

Step 7.main — Spawn the verifier

After the executor opens the draft PR, spawn bug-fix-verifier in a fresh context with no access to planner / executor reasoning. The verifier runs four checks: FAIL_TO_PASS, PASS_TO_PASS, diff sanity, repro integrity. On green it runs gh pr ready to undraft the PR; on red it leaves the PR draft and surfaces the verifier's evidence to the user.

See rules/independent-verification.md for the full procedure. Source: Effective harnesses for long-running agents (Anthropic) — "agents reliably skew positive when grading their own work."

On a verifier RED verdict, write a lesson — the fix was wrong despite all three gates, which is the highest-signal moment to capture which earlier phase under-caught it (triage too simple? repro false-green? analysis wrong file?). Classify scope, dedup, then write:

memory.search { q: "<lesson keywords>", scopes: ["repo::{owner}/{repo}", "global"], limit: 10 }     # no-op if memory.* not connected
memory.write { scope: "<global | repo::{owner}/{repo}>", key: "fix-bug-lessons::<slug>", value: "<body>", tags: ["loop::fix-bug-lessons", "source::verifier-red"], source_agent: "fix-bug", trigger: "verifier-red" }

See rules/self-improvement-loop.md.

---

Phase 8 — Telemetry Verification

Runs only when the original input was a Dash0 / telemetry URL and the PR has been merged and deployed.

The fix is not done at merge — it is done when the originating signal stops firing in production. What "stops firing" means depends on how often the bug fires. Phase 8 classifies the bug's observability shape (baseline rate, crash-class, cohort, release attribution) and picks one of five modes:

Mode	When
Rate-decay	High-frequency bugs (≥ 10 events / 30 min baseline) — poll for 30 min; pass at ≤ 5% of baseline
Extended watch	Low-frequency bugs (1–9 events / 30 min, or sparse over hours) — watch for 24 h–7 d; pass on absence
Cohort absence	One-shot bugs with a known cohort (user / tenant / device) — watch the cohort for 7 d
Build-version absence	Crash-class bugs with release attribution (Crashlytics-style) — pass at N crash-free sessions or 7 d
Deferred-watch	One-shot bugs with no cohort and no release attribution, or MCP capability gate failed — register a manual watch (default 14 d), close provisionally, reopen on recurrence

Deferred-watch is the honest answer for app crashes that fired once with no cohort information. The skill does not pretend to verify in that mode — it registers the watch on the Linear ticket and PR, closes the bug as "deployed; watching for recurrence", and reopens if the originating query produces a match on the new release tag.

See rules/telemetry-verification.md for the full classification procedure and per-mode operations.

Default operating mode is deferred — emit a follow-up task to be re-invoked once the deploy lands (/fix-bug --verify-deploy <PR>). The --inline-verify flag opts into running synchronously when the project auto-deploys on merge.

If the originating signal does not decay (or recurs), write a lesson — this is the strongest evidence that the "fix" did not fix the production symptom, and almost always points back to a Phase 3 analysis or Phase 2.5 repro-fidelity gap. Classify scope, dedup, then write:

memory.search { q: "<lesson keywords>", scopes: ["repo::{owner}/{repo}", "global"], limit: 10 }     # no-op if memory.* not connected
memory.write { scope: "<global | repo::{owner}/{repo}>", key: "fix-bug-lessons::<slug>", value: "<body>", tags: ["loop::fix-bug-lessons", "source::telemetry-firing"], source_agent: "fix-bug", trigger: "telemetry-firing" }

See rules/self-improvement-loop.md.

---

Self-Improvement

/fix-bug improves across bugs through a two-tier loop (full contract: rules/self-improvement-loop.md).

Fast tier — episodic lessons (LoreKit memory.*, optional). Reads fix-bug-lessons (tag loop::fix-bug-lessons) at Phase 0.5 (keyed by bugClass + input shape) and writes lessons at the highest-signal failure moments — verifier RED (Phase 7), telemetry-still-firing (Phase 8), triage upgrades, and Phase 5 stops. Each lesson is classified to the global scope (universal bug classes) or the repo::{owner}/{repo} scope (project-bound bug patterns). Lessons cover fix-bug's own diagnostic phases; implementation-phase lessons live in aw-lessons (written by aw-executor). Lessons are advisory and the loop is a silent no-op if LoreKit's memory.* tools are not connected.

Slow tier — retrospective diagnosis. If a run shipped wrong code despite all three confidence gates — or a post-merge regression traces back 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. The diagnoser reads this skill's diagnostic surface and the fix-bug-lessons history as evidence, and emits a confidence-gated diff against this skill's source — never against user product code.

---

Output Format

Use this format for every Phase 5 outcome — auto-fix, proposal-only, or --analyse-only. The shape stays stable; only the tail varies.

## Fix-bug summary

### Evidence
<Evidence Record from Phase 2, including bugClass and pre-flight findings>

### Triage (Phase 0.5)
- Classification: simple | complex
- Phase 6 lane: fast-lane | standard-lane | n/a (analyse-only) | n/a (below gate)
- Decision rule applied: <rule>
- Override: --force-holistic | none

### Reproduction
<repro path + command + status>

### Root cause
<one paragraph from holistic-analysis OR lightweight in-skill analysis — labelled accordingly>

### Proposed change
<plain-language description + impact + verification plan>

### Confidence (analysis)
- Evidence strength: X%
- Root cause certainty: X%
- Fix confidence: X%
- **Overall: X%**

### Outcome
<one of:>
- Auto-implemented (<lane>) + verified: PR <url> on branch <name>. Verifier green. Telemetry decayed.
- Auto-implemented (<lane>), verifier red: PR <url> still draft. Concerns: <list>.
- Auto-implemented (fast-lane → standard-lane fallback): PR <url>. Round-3 CEGIS triggered fallback. Verifier <status>.
- Analyse-only (no PR): proposal returned at X% confidence; triage = <simple | complex>.
- Below gate (X%): proposal returned for review. To raise the score, collect: <specific evidence>.
- Stopped: <reason>.

---

Risks and Mitigations

Risk	Likelihood	Mitigation
Free-text input triggers low-confidence holistic analysis	Medium	Phase 0 refuses to analyse on free text alone — clarifying questions first. Phase 0.5 triage also picks complex for free-text (signal 11).
Dash0 MCP not configured	Medium	Detection step in evidence-resolution.md prints the install / paste-evidence fallback; Phase 8 has its own capability gate.
Repro is best-effort only (UI / race / perf)	Medium	Verifier (Phase 7) skips FAIL_TO_PASS and relies on broader test suite + diff sanity. Best-effort repros are also blocked from the fast-lane — they always route via standard-lane. Documented in the bug-notes ledger.
Analysis returns a confident-but-wrong root cause	Low–Medium	Three independent gates on both lanes: standard-lane uses confidence(analysis) + confidence(plan) + verifier; fast-lane uses confidence(analysis) ≥ 92 % (stricter substitute for confidence(plan)) + plan.md validator + verifier.
Triage classified simple but the bug was cross-cutting	Low–Medium	Fast-lane round-3 CEGIS failure falls back to standard-lane via aw-planner with the captured counterexamples — single-shot safety net.
Triage classified complex but the bug was trivial	Medium	Acceptable. Wasted tokens; no correctness loss. Conservative default is intentional. Pre-flight short-circuit can still upgrade complex → simple later in the run.
Fast-lane plan.md missing a required section	Low	/fix-bug validates plan.md after aw-create-plan returns and before dispatching aw-executor. Fails loudly.
Executor's first patch fails the repro	Medium	CEGIS refinement contract: capture failing input as counterexample, refine, cap at 3 rounds before escalating (standard-lane → confidence(analysis fix); fast-lane → standard-lane fallback).
Verifier rubber-stamps the executor's diff	Low	Verifier runs in fresh context with no access to planner / executor reasoning — the canonical separation-of-concerns mitigation. Identical on both lanes.
Bug-notes ledger drifts from reality	Low	Schema is strict; phases append rather than rewrite; verifier reads the ledger as evidence.
Phase 8 polls the wrong release	Low	Capability gate plus explicit deploy-ID capture; falls back to deferred mode for production deploys.

---

Key Principles

1. Orchestrate, don't analyse. Holistic analysis lives in holistic-analysis, 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, grading in bug-fix-verifier.
2. Match the harness to the bug. A null-check fix in one file does not need an eight-phase pipeline. Phase 0.5 triage routes simple bugs to a lightweight in-skill analysis and a fast handoff lane; complex bugs get the full holistic-analysis + planner treatment. The conservative default is complex — when in doubt, run the slower lane.
3. Reproduce before fixing. The repro is the executor's FAIL_TO_PASS contract and the verifier's primary check. Best-effort fallback is allowed but flagged — and blocks the fast-lane.
4. Cheap localisation first. Pre-flight (Phase 1.5) often names the cause in seconds — running heavy holistic analysis first wastes tokens. Pre-flight short-circuits can also upgrade complex triage to simple and unlock the fast-lane.
5. Three independent confidence gates on both lanes. Standard-lane: confidence(analysis)
   • confidence(plan) + verifier. Fast-lane: confidence(analysis) ≥ 92 % (stricter substitute for the bypassed planner gate) + plan.md validator + verifier. Self-grading is not allowed at any of these.
6. Auto-implement at ≥ 92 % is fully autonomous. No human confirmation. The skill prints a one-line status and dispatches. Below 92 % the skill stops and asks. The threshold is the substitute for the bypassed planner gate on the fast-lane and applies symmetrically on the standard-lane to keep the user-facing model simple.
7. Counterexample-driven refinement. When a patch fails the repro, the failing input is the evidence — capture it, refine, cap at 3 rounds. On fast-lane, round-3 failure additionally falls back to standard-lane via aw-planner with the counterexamples appended.
8. Durable ledger over re-derived state. The bug-notes ledger survives compaction; phases read on entry and append on exit. Triage decisions, lane choices, downgrades, and fallback triggers are all logged. Re-derivation is the failure mode the ledger prevents.
9. No force-proceed under 70 %. Below 70 % the skill stops and hands back to the user. No escape hatch. Force-proceed on 70–91 % always routes to standard-lane.
10. Telemetry sources close their own loop. A Dash0-sourced bug is not done until the originating query stops firing. Phase 8 enforces this. Same for both lanes.
11. Linear is one input adapter among several. A Linear URL routes through linear-ticket-investigator to produce an Evidence Record, then continues at Phase 2 like any other input. /batch-linear-tickets does not wrap /fix-bug — its Phase 1 dispatches linear-ticket-investigator (and holistic-analysis for bug tickets) per ticket directly.
12. Learn across bugs, but only advisory. fix-bug-lessons (read Phase 0.5, write Phase 5/7/8) biases triage / repro / analysis from prior misfires; it never relaxes a gate. A lesson recurring seen_count >= 3 is promoted into a permanent guard only through the confidence-gated diagnose apply. Implementation-phase learning lives in aw-lessons via aw-executor.