Cursor rule

1---
2description: "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."
3alwaysApply: false
4---
5 
6# Fix Bug
7 
8**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.
9 
10Orchestrates **fix_bug** flow without mixing epic build state.
11 
12> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.
13 
14## Discovered gate failures (e51s04)
15 
16Valid entry **without a user-reported bug** when:
17 
18- **Preflight** or **CI** is red at kickoff or verify-work
19- **Golden suite** or project baseline is red (`bash scripts/run-verification-gates.sh` or equivalent)
20- A reproducible gate failure during unrelated epic work exceeds quick-fix guardrails
21 
22Create `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.
23 
24## Five steps (`bug_cycle` in state.yaml)
25 
26| Step | Skill / action |
27|------|----------------|
28| 1 | `investigate-bug` — create BUG-*.md with RCA |
29| 2 | `diagnose-root` — 4-phase root cause analysis |
30| 3 | `develop-tdd` — red-green against bug file verify steps |
31| 4 | `validate-fix` — re-run failing test, full suite, lint |
32| 5 | `release-branch` — PR or solo land the fix |
33 
34### Checkpoint / resume
35 
36Track progress via `specs/state.yaml` `bug_cycle`:
37- `bug_cycle.current_step`: current step (1–5)
38- `bug_cycle.completed_steps`: completed step numbers
39- `handoff.next_skill`: skill for the current step
40- On resume, read `bug_cycle.current_step` and continue from there
41 
42## Process
43 
441. **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.
452. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3.
463. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green.
474. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5.
485. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.
49 
50## Bug file SoT
51 
52One markdown file per bug with frontmatter:
53 
54```yaml
55---
56bug_id: BUG-001
57status: open
58severity: high
59scope: api
60title: Short title
61---
62```
63 
64## Verify
65 
66→ verify: `test -d specs/bugs && test -f scripts/run-skill-verify.sh`
67