bugfix

Bugfix workflow

When a bug, failing test, error, regression is reported — follow this exact sequence.

1. Reproduce

• Establish the smallest reliable repro path (test, command, sequence of clicks, payload).
• If you cannot reproduce — STOP and ask owner for repro steps. Do not "fix" what you cannot reproduce.

2. Read code BEFORE hypothesis (R1)

• Read the file(s) implicated in the failure. Do not skim — actually Read with the tool.
• If the issue touches an external SDK/API → trigger official-docs-first skill (R2).
• Cite specific file:line in your reasoning.

3. Identify root cause

• Walk the failing path from symptom backwards.
• Check git log of the failing file: git log -p --follow <file> — recent changes?
• Use Grep/Serena find_references for related call sites.
• Hypothesis is OK only AFTER reading. Mark explicitly: "Hypothesis (unverified): X. Verifying via Y."

4. Fix the CAUSE not the symptom (R10 — No band-aids)

• Architecturally correct fix, not a try/catch wrapper.
• If correct fix is larger than the bug warrants — write ADR + propose follow-up TZ instead of patching.

5. Validate (R12)

• Add or update test that would have caught this bug.
• Run pytest tests/test_X.py or equivalent. Must PASS.
• Run mypy/ruff on touched files. Must be CLEAN.

6. Update memory

• If issue partially resolved or revealed deeper problem → record in docs/agent/06_known_issues.md.
• If incident-worthy → start docs/agent/08_postmortems.md entry.
• Append to docs/agent/04_changelog.md.

7. ADR if architectural decision was made

• "Switched from X to Y to fix this" = architectural decision = needs ADR.
• "Patched edge case in Y" = not architectural, no ADR needed.

Anti-patterns (do NOT do these)

• ✗ Catch exception silently
• ✗ Add try/except: pass
• ✗ Add boolean flag to skip the broken path
• ✗ Wrap bug with comment "// FIXME: weird issue, working around"
• ✗ Mark task done without test that verifies the fix