Bugfix

1. Read docs/contributing.md and CLAUDE.md for project conventions.
2. Implement the fix following all code guidelines.
3. Add or update tests covering the bug scenario.
4. Run the full test suite to confirm nothing is broken.

Phase 4 — Update user stories and docs

This step is mandatory. After every bugfix:

1. Identify which user story or spec doc in docs/features/ covers the area that was broken.
2. Update the doc to reflect the fix — add acceptance criteria, verification steps, or edge case documentation that was missing.
3. If the bug revealed a gap in the spec (e.g., an unhandled error state), document the new behavior so it is covered going forward.

If no existing doc covers the area, mention this to the user and ask if they want a new doc or an addition to an existing one.

Phase 5 — Summary

Present a summary:

• Root cause (one sentence)
• What was fixed
• What tests were added
• What docs were updated