bug-fix

Imported from rithvik318/ai-shadow (.claude/skills/bug-fix/SKILL.md). Install upstream with npx skills add rithvik318/ai-shadow --skill bug-fix. Copyright stays with the author.

Bug Fix

Purpose

Fix defects in AI Shadow by identifying and addressing the root cause, not the symptom, and prevent recurrence with a regression test. A bug fix is only complete when the underlying cause is understood and explained, not merely when the observed symptom disappears.

When to use this skill

Use bug-fix whenever behavior doesn't match what's expected or documented — a reported issue, a failing test, an exception, or incorrect output discovered while working on something else. Do not use it to add new functionality, and do not use it for pure code-quality cleanup where nothing is actually broken (refactoring covers that).

Workflow

1. Read CLAUDE.md

Read it in full before investigating, particularly §6 (Coding Standards) and §9 (Testing Standards), since the fix and its regression test must follow those conventions.

2. Understand the bug precisely

Establish exactly what's happening versus what should happen: the precise trigger conditions, the actual output/error, and the expected output/behavior. If the bug isn't reproducible yet, reproduce it first — do not guess at a fix from a description alone.

3. Investigate the root cause

Trace the failure back through the code to its actual origin. Check the full call path, relevant configuration (app/config/settings.py), and any related tests. Do not stop at the first plausible-looking culprit — confirm it by tracing exactly how it produces the observed symptom. Check docs/KNOWN_ISSUES.md in case this bug (or something related) is already tracked with useful context.

4. Distinguish root cause from symptom

Before writing any fix, be able to state in one sentence why the bug occurs — not just where it manifests. A fix that suppresses an exception, adds a defensive null-check, or special-cases a particular input without explaining why the invalid state arose in the first place is very likely a symptom fix, not a root-cause fix.

5. Implement the minimal, targeted fix

Fix the actual cause, following existing repository patterns (CLAUDE.md §7/§8 if the fix touches prompts or LLM provider code). Keep the change as small as correctly fixing the root cause allows.

6. Add a regression test

Add a test that fails against the old (buggy) code and passes against the fix, placed following the conventions in backend/tests/ (mirroring backend/app/ structure, per the pattern in backend/tests/prompts/). A bug fix without a regression test is incomplete.

7. Run the full test suite

Confirm the regression test passes and that no other existing test broke as a side effect of the fix.

8. Explain the cause and the fix

State plainly: what the root cause was, why it produced the observed symptom, and what the fix changes to address it. This explanation is part of the deliverable, not optional narration.

9. Update docs/KNOWN_ISSUES.md if applicable

If this bug was already tracked there, mark it resolved (or remove the entry) as part of this same change.

10. Keep the commit scoped

The commit contains this one fix only — do not bundle in other bugs discovered along the way; note them separately instead.

Best Practices

• Reproduce before fixing — never patch based on a description alone if reproduction is possible.
• Write or run the regression test against the unfixed code first to confirm it actually catches the bug.
• Check docs/KNOWN_ISSUES.md for prior context before starting from scratch.
• Keep the fix minimal and targeted at the actual cause.
• If you discover an unrelated bug while fixing this one, note it (e.g., flag it) rather than fixing it in the same change.

Common Mistakes to Avoid

• Fixing the symptom, not the cause — e.g., catching an exception instead of fixing why it's raised, or adding a null-check instead of fixing why a null arrives.
• Skipping the regression test, leaving no protection against recurrence.
• Assuming the root cause without tracing the actual failure path.
• Fixing multiple unrelated bugs in a single commit.
• Not updating docs/KNOWN_ISSUES.md when a previously tracked issue is resolved.
• Omitting the explanation of cause and fix, leaving future readers to re-diagnose the same issue.

Completion Checklist

• CLAUDE.md was read before investigating.
• The bug was reproduced or its exact trigger conditions were confirmed.
• The root cause was identified by tracing the actual failure path, not assumed.
• The fix addresses the root cause, not just the observed symptom.
• A regression test was added, confirmed to fail before the fix and pass after.
• The full test suite passes, including all previously existing tests.
• A clear explanation of the root cause and the fix was provided.
• docs/KNOWN_ISSUES.md was updated if this issue was previously tracked there.
• The commit is scoped to this single fix.