Windsurf rules

1---
2name: investigate-bug
3model: sonnet
4description: "Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions \"triage\", or wants to plan a fix."
5---
6 
7# Investigate Bug
8 
9**Boundary**: End-to-end bug entry point — history check → RCA (via `diagnose-root`) → fix approach → TDD plan → bug file. Delegates the 4-phase RCA to `diagnose-root`; does not re-implement it.
10 
11Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/bugs/BUG-*.md`. This is a mostly hands-off workflow — minimize questions to the user.
12 
13## Process
14 
15### 0. Read previous bug history
16 
17Before starting diagnosis:
18 
191. Read `specs/bugs/registry.yaml` (if it exists) — check for prior bugs in the same `scope` or with similar symptoms.
202. If a relevant prior bug is found, read the corresponding `specs/bugs/BUG-*.md` file to understand previous root cause analysis and fix approach.
213. Note in your investigation whether this is a recurrence, a related issue, or novel.
22 
23### 1. Capture the problem
24 
25Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"
26 
27Do NOT ask follow-up questions yet. Start investigating immediately.
28 
29> **Security-impact assessment** — After capturing the problem, assess and document: `Security impact: NONE / LOW / MEDIUM / HIGH / CRITICAL`. If HIGH or CRITICAL, assign bug severity HIGH and document the exploit path in findings. If MEDIUM+, include exploit path in the bug file. Document "no security exploit path identified" for NONE/LOW.
30 
31### 2. Explore and diagnose (4-phase RCA)
32 
33Run the 4-phase root-cause analysis via the `diagnose-root` skill (Reproduce → Isolate → Hypothesize → Verify). That skill is the canonical RCA engine — do not re-implement the phases here.
34 
35Also look at:
36- Recent changes to affected files (`git log --oneline <file>`)
37- Existing tests (what's tested, what's missing)
38- Similar patterns elsewhere in the codebase that work correctly
39 
40> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until `diagnose-root` Phase 4 produces a verified root cause. "It probably is X" is not verified.
41 
42### 3. Identify the fix approach
43 
44Based on your investigation, determine:
45 
46- The minimal change needed to fix the root cause
47- Which modules/interfaces are affected
48- What behaviors need to be verified via tests
49- Whether this is a regression, missing feature, or design flaw
50- Risk level: Low / Medium / High
51 
52### 4. Design TDD fix plan
53 
54Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:
55 
56- **RED**: Describe a specific test that captures the broken/missing behavior
57- **GREEN**: Describe the minimal code change to make that test pass
58 
59Rules:
60- Tests verify behavior through public interfaces, not implementation details
61- One test at a time, vertical slices (NOT all tests first, then all code)
62- Each test should survive internal refactors
63- Include a final refactor step if needed
64- **Durability**: Only suggest fixes that would survive radical codebase changes. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state.
65 
66### 5. Write the bug file
67 
68Save the investigation and fix plan to `specs/bugs/BUG-NNN-slug.md`. Create the `specs/bugs/` directory if it doesn't exist.
69 
70After writing, append a row to `specs/bugs/registry.yaml` with: bug_id (same timestamp), date, severity, priority, scope, summary, and file path. Create `specs/bugs/registry.yaml` if it doesn't exist.
71 
72<diagnosis-template>
73 
74# BUG-YYYY-MM-DDTHHMMSS: [short title]
75 
76## Problem
77 
78A clear description of the bug or issue, including:
79- What happens (actual behavior)
80- What should happen (expected behavior)
81- How to reproduce (if applicable)
82 
83## Root Cause Analysis
84 
85Describe what you found during investigation:
86- The code path involved
87- Why the current code fails
88- Any contributing factors
89- Risk level: Low / Medium / High
90 
91Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead.
92 
93## TDD Fix Plan
94 
95A numbered list of RED-GREEN cycles:
96 
971. **RED**: Write a test that [describes expected behavior]
98   **GREEN**: [Minimal change to make it pass]
99   **verify**: [runnable command]
100 
1012. **RED**: Write a test that [describes next behavior]
102   **GREEN**: [Minimal change to make it pass]
103   **verify**: [runnable command]
104 
105**REFACTOR**: [Any cleanup needed after all tests pass]
106 
107## Acceptance Criteria
108 
109- [ ] Criterion 1
110- [ ] Criterion 2
111- [ ] All new tests pass
112- [ ] Existing tests still pass
113 
114## Resolution
115 
116<!-- filled in by validate-fix -->
117 
118</diagnosis-template>
119 
120After writing the bug file, print a one-line summary of the root cause and suggest running `kickoff-branch` next to create a fix branch.
121 
122## References
123 
124<!-- story: e35s10 -->
125 
126- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
127- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating
128