The Bugfix Spec models how experienced developers approach bug fixes: identify the root cause, understand what should change, and explicitly preserve what shouldn't. Bugfix Specs provide a structured approach using that workflow, guiding you through root cause analysis, fix design, and regression prevention.
Scoped fixes - Explicit constraints ensure only necessary changes are made
Regression prevention - Unchanged behavior is documented and tested
Documentation - Complete record of the bug, fix, and reasoning for future reference
Reliability - Structured workflow prevents common pitfalls of ad-hoc fixes
Best for:
- Complex bugs requiring root cause analysis
- Bugs in critical code paths where regressions are costly
- Bugs that need documentation for compliance or team knowledge
- Situations where previous fix attempts caused regressions
Bugfix Specs follow the same three-phase workflow as Feature Specs (Requirements → Design → Tasks), but with content tailored specifically for bug fixes:
Instead of a requirements document, you create a bugfix.md that captures:
Current Behavior (Defect)
- WHEN [condition] THEN the system [incorrect behavior]
Expected Behavior (Correct)
- WHEN [condition] THEN the system SHALL [correct behavior]
Unchanged Behavior (Regression Prevention)
- WHEN [condition] THEN the system SHALL CONTINUE TO [existing behavior]
This explicit structure ensures Kiro understands not just what's broken, but what must remain working.
Kiro explores the codebase to root cause the issue and generates a design.md with:
- Root cause analysis
- Proposed fix approach
- Properties to test for:
- Current implementation produces incorrect behavior (validates the bug exists)
- Fixed implementation produces correct behavior (validates the fix works)
- Unchanged implementation continues working (prevents regressions)
Implementation tasks are generated with property-based tests (PBTs) that validate:
- The bug is reproducible
- The bug is fixed
- No regressions are introduced
- Choose Bug Fix from the workflow options on the "Let's build" screen when starting a new session. To switch mid-session, click the agent name in the bottom bar of the chat input and select Bug Fix from the agent picker.
- Describe the bug, including:
- When the bug occurs (reproduction steps)
- What should happen instead
- Any constraints (code that shouldn't be modified)
- Follow the workflow through analysis, design, and implementation.
Bugfix Specs