/fix-bug

# story: e51s04
name: fix-bug
model: sonnet
effort: standard
description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect.

Fix Bug

**Boundary**: Orchestrator flow — chains `investigate-bug` (entry point + RCA via `diagnose-root`) → `develop-tdd` → `validate-fix`. Does not implement RCA or write bug files directly.

Orchestrates **fix_bug** flow without mixing epic build state.

> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.

Discovered gate failures (e51s04)

Valid entry **without a user-reported bug** when:

• **Preflight** or **CI** is red at kickoff or verify-work
• **Golden suite** or project baseline is red (`bash scripts/run-verification-gates.sh` or equivalent)
• A reproducible gate failure during unrelated epic work exceeds quick-fix guardrails

Create `specs/bugs/BUG-*.md` via `investigate-bug` (or inline in fix-bug step 1) describing the gate failure, then run the standard fix_bug chain.

Five steps (`bug_cycle` in state.yaml)

| Step | Skill / action | |------|----------------| | 1 | `investigate-bug` — create BUG-*.md with RCA | | 2 | `diagnose-root` — 4-phase root cause analysis | | 3 | `develop-tdd` — red-green against bug file verify steps | | 4 | `validate-fix` — re-run failing test, full suite, lint | | 5 | `release-branch` — PR or solo land the fix |

Checkpoint / resume

Track progress via `specs/state.yaml` `bug_cycle`:

• `bug_cycle.current_step`: current step (1–5)
• `bug_cycle.completed_steps`: completed step numbers
• `handoff.next_skill`: skill for the current step
• On resume, read `bug_cycle.current_step` and continue from there

Process

1. **Step 1 — investigate-bug:** If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file. Increment `bug_cycle.current_step` to 2 on completion. 2. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3. 3. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green. 4. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5. 5. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.

Bug file SoT

One markdown file per bug with frontmatter:

---
bug_id: BUG-001
status: open
severity: high
scope: api
title: Short title
---

Verify

→ verify: `test -d specs/bugs && test -f scripts/run-skill-verify.sh`