Verified by AI Team

This flow has been practiced in daily development. The bug classification decision tree effectively guides fix strategies.

Bug Fix Flow

Bug fixes follow a different workflow than new features. The key question: Does this bug indicate a spec problem or an implementation problem?

Bug Classification Decision Tree

Flow by Bug Type

Bug Type	Spec Change	Flow
Implementation Bug	No	Diagnose -> Fix -> Test -> Commit
Spec Gap	Yes (clarify)	Diagnose -> Update spec (add scenario) -> Fix -> Test -> Commit
Spec Bug	Yes (proposal)	Diagnose -> Create proposal -> Review -> Fix -> Test -> Archive
Edge Case	Yes (extend)	Diagnose -> Add scenario to spec -> Implement -> Test -> Commit

Implementation Bug Flow (No Spec Change)

Steps

1. Diagnose - Identify root cause, locate relevant spec
2. Verify - Confirm spec defines expected behavior, implementation deviates
3. Fix - Agent generates fix aligned to spec
4. Review - Human verifies fix matches spec intent
5. Test - Verify fix, no regression
6. Commit - Direct commit, no proposal needed

Spec Gap/Extension Flow (Spec Update Required)

Steps

1. Diagnose - Identify uncovered edge case
2. Update Spec - Add scenario describing expected behavior
3. Fix - Agent implements newly specified behavior
4. Review - Human verifies spec addition and implementation
5. Commit - Spec and code committed together (atomic)

Spec Bug Flow (Design Flaw)

Steps

1. Diagnose - Identify spec design flaw
2. Create Proposal - Document why spec is wrong, propose correction
3. Review Proposal - Team validates spec change
4. Implement - Agent implements corrected behavior
5. Archive - Full proposal flow, spec updated to specs/

Agent Role in Bug Fixes

Phase	Agent Contribution
Diagnosis	Search codebase, identify potential root causes, locate relevant specs
Spec Analysis	Compare implementation against spec, highlight discrepancies
Fix Generation	Generate fix aligned to spec (or proposed spec change)
Test Generation	Generate test cases covering the bug scenario
Regression Check	Identify potentially affected areas

Key Principles for Bug Fixes

1. Spec is truth - If code doesn't match spec, code is wrong (unless spec is flawed)
2. Atomic commits - Spec changes and code fixes committed together when related
3. No silent fixes - Spec gaps discovered during bug fix MUST be documented
4. Test the scenario - Every bug fix should add a test covering the failure case

Anti-patterns

Anti-pattern	Problem	Correct Approach
Fix without checking spec	May "fix" intended behavior	Always locate relevant spec first
Update spec to match buggy code	Legitimizes bugs	Spec reflects intent, not accidents
Skip spec update for edge cases	Gap remains undocumented	Add scenario even for "obvious" fixes
Large spec changes via bug fix	Bypasses proposal review	Significant changes need proposals

Related: Workflow Framework Overview