| name | fix-issue |
| description | Diagnose and fix a bug in the existing codebase. Enforces: reproduce first, write failing test, implement smallest fix, verify all tests pass, document root cause. |
Fix Issue
Input
The user will describe the bug, error message, or unexpected behavior.
Process
1. Understand the Issue
Read docs/ARCHITECTURE.md and docs/FEATURES.json to identify the affected area.
2. Reproduce the Issue
NEVER skip reproduction. Read the code, run existing tests, reproduce manually if possible. If you can't reproduce, document what you tried and ask for more details.
3. Root Cause Analysis
Trace the call chain. Check recent git commits. Check if the same pattern exists elsewhere. Classify: logic error, data error, integration error, configuration error, or regression.
4. Write a Failing Test FIRST
Write a test that reproduces the exact bug scenario — it must FAIL with current code and PASS after the fix.
5. Implement the Fix
Smallest possible change. Don't refactor surrounding code. Fix all occurrences if the same bug exists elsewhere.
6. Verify
Run the new test (should pass). Run ALL existing tests (nothing else should break). Reproduce original issue (should be gone).
7. Log the Fix
Add a B-prefix entry to docs/FEATURES.json with status "complete". Update docs/PROGRESS.md with root cause, fix, and regression test. Commit: fix(B###): description
8. Check for Systemic Issues
Is this a pattern that could exist elsewhere? Suggest /refactor if so.
Rules
- ALWAYS reproduce before fixing
- ALWAYS write a failing test first
- ALWAYS run full test suite after
- Smallest possible change
- Document the root cause
