| name | Fixing Bugs Systematically |
| description | Diagnose and fix bugs through systematic investigation, root cause analysis, and targeted validation. Use when something is broken, errors occur, performance degrades, or unexpected behavior manifests. |
Fixing Bugs Systematically
Structured protocol for isolating root causes and implementing focused fixes in existing features.
When to Use
- Something is broken and needs diagnosis and repair
- Error messages or unexpected behavior occurs
- Performance degradation in existing functionality
- Intermittent or hard-to-reproduce issues
Core Steps
1. Context & Reproduction
Read relevant documentation:
docs/feature-spec/F-##-*.md for affected featuredocs/user-stories/US-###-*.md for expected behavior and acceptance criteriadocs/api-contracts.yaml if API-relateddocs/system-design.md for architecture context
Document the bug:
- Expected behavior (cite story AC or spec)
- Actual behavior (what's broken)
- Reproduction steps
- Feature ID (F-##) and Story ID (US-###) if known
2. Investigation
Simple bugs (obvious entry point)
Use direct investigation:
- Grep to locate error messages or related code
- Read suspected files to examine implementation
- Trace function calls and data transformations
- Check related files for connected logic
Complex bugs (multiple subsystems or unclear origin)
Delegate to async agents in parallel:
Spawn agents to:
