Fix a Bug With a Bugfix Spec

A bugfix spec is Kiro’s spec workflow applied to a defect. The analysis goes into bugfix.md rather than requirements.md, and the fix is designed and reviewed before any code changes.

When to use this

Use a bugfix spec when the bug is intermittent, when the root cause is not obvious, when the fix touches something risky, or when the same bug has come back before. Skip it for a typo. The value is the written record: six months later, bugfix.md explains why the code looks the way it does.

Steps

1. Reproduce the bug first, by hand if necessary. A spec built on a guessed symptom designs the wrong fix.

2. Create a new spec and choose the bugfix workflow. In the IDE, start from the Kiro panel or the Command Palette. In the CLI, /spec new opens a guided description step before generation.

3. Describe the bug in facts, not theories:

   Stock reservations sometimes never expire. Seen twice in
   production this month. Both times the reservation row still had
   status=active with expires_at in the past. No error in the logs.
   The expiry job ran on schedule on both days.

4. Review bugfix.md. It should record the symptoms, the root cause, and the blast radius. Push back on any root cause the evidence does not support. This is the step that pays for the whole workflow.

5. Review design.md for the fix. Check the failure modes, not just the happy path.

6. Open tasks.md and reorder if you need to, so the first task is a failing regression test that reproduces the bug. The fix comes second. That order proves the test actually catches the bug.

7. Execute the tasks. Watch the regression test fail, then pass. In the CLI, /spec run opens the full-screen task execution view (v2.20.0) where you choose the scope before execution starts.

8. Commit the spec folder under .kiro/specs/ with the fix.

Check it worked

The regression test must fail on the code before the fix and pass after it. If it passes both times, it does not test the bug. Read bugfix.md once more after the fix lands and confirm the root cause it names matches what you actually changed. A mismatch means the spec described one bug and you fixed another.

Common problems

• The root cause is a guess. The agent will write a plausible cause from the symptoms. Make it point at evidence in the code or the logs.
• The regression test passes immediately. It tests the wrong path. Run it against the unfixed code to prove it catches the bug.
• The fix grows. A bugfix spec that starts refactoring is two pieces of work. Split it, and use a feature spec for the second.
• The session goes wrong mid-fix. Restore a checkpoint rather than un-picking edits by hand. See Checkpoints and rewind.
• Nobody reads the spec later. Commit it. A bugfix.md that lives only in a chat transcript is not a record.

Related

• Specs covers the three-phase workflow and EARS notation.
• Advanced Tutorial shows bugfix specs inside a team workflow.
• Run tests on save with a hook keeps the regression test running.