1. Load the

   outfitter:maintain-tasks

   skill for stage tracking
2. Collect evidence (reproduce, gather symptoms)
3. Isolate variables (narrow scope)
4. Formulate and test hypotheses
5. Implement fix with failing test first
6. Verify fix resolves the issue

• Bugs, errors, exceptions, crashes
• Unexpected behavior or wrong results
• Failing tests (unit, integration, e2e)
• Intermittent or timing-dependent failures
• Performance issues (slow, memory leaks, high CPU)
• Integration failures (API, database, external services)

<stages>

• Iterate -> Hypothesis disproven, loops back with new hypothesis

• Start: "Collect Evidence" as

  in_progress

• Transition: Mark current

  completed

  , add next

  in_progress

• Failed hypothesis: Add "Iterate" task
• Quick fixes: If root cause obvious from error, skip to "Verify Fix" (still create failing test)
• Need more evidence: Add new evidence task (don't regress stages)
• Circuit breaker: After 3 failed hypotheses -> escalate

</stages>

1. Create "Collect Evidence" todo as

   in_progress

2. Reproduce - exact steps to trigger consistently
3. Investigate - gather evidence about what's happening
4. Analyze - compare working vs broken, find differences
5. Test hypothesis - single specific hypothesis, minimal test
6. Implement - failing test first, then fix
7. Update todos on stage transitions

• Stack traces top to bottom
• Note file paths, line numbers, variable names
• Look for "caused by" chains

• Document exact trigger steps
• Note inputs that cause vs don't cause
• Check if intermittent (timing, race conditions)
• Verify in clean environment

• git diff

  - what changed?

• git log --since="yesterday"

  - recent commits
• Dependency updates
• Config/environment changes

• Add logging at key points
• Print variable values at transformations
• Log function entry/exit with parameters
• Capture timestamps for timing issues

• Where does bad value come from?
• Track through transformations
• Find first place it becomes wrong

• "I think maybe X is the problem"
• "Let's try changing Y"
• "It might be related to Z"
• Starting to write code before understanding

• Search for similar functionality that works

• rg "pattern"

  for similar patterns
• Look for passing vs failing tests
• Check git history for when it worked

• Every line, not skimming
• Full context
• All dependencies/imports
• Configuration and setup

• Line by line working vs broken
• Different imports?
• Different function signatures?
• Different error handling?
• Different data flow?
• Different configuration?

• Libraries/packages involved
• Versions in use
• External services
• Shared state
• Assumptions made

• Why does working version work?
• What's fundamentally different?
• Edge cases working version handles?
• Invariants working version maintains?

• Template: "X is root cause because Y"
• Must explain all symptoms
• Must be testable with small change
• Must be based on evidence from stages 1-2

• Smallest change to test hypothesis
• Change ONE variable
• Preserve everything else
• Make reversible

• Apply change
• Run reproduction steps
• Observe carefully
• Document results

• Fixed: Confirm across all cases, proceed to Verify Fix
• Not fixed: Mark complete, add "Iterate", form NEW hypothesis
• Partially fixed: Add "Iterate" for remaining issues
• Never: Random variations hoping one works

• "Maybe it's a race condition"
• "Could be caching or permissions"
• "Probably something with the database"

• "Fails because expects number but receives string when API returns empty"
• "Race condition: fetchData() called before initializeClient() completes"
• "Memory leak: event listeners in useEffect never removed in cleanup"

• Write test reproducing bug
• Verify fails before fix
• Should pass after fix
• Captures exact broken scenario

• Address identified root cause
• No additional "improvements"
• No refactoring "while you're there"
• Just fix the problem

• Failing test now passes
• Existing tests still pass
• Manual reproduction no longer triggers bug
• No new errors/warnings

• Problem isn't hypothesis - problem is architecture
• May be using wrong pattern entirely
• Escalate or redesign

• Mark "Verify Fix" completed
• Add defensive validation
• Document root cause
• Consider similar bugs elsewhere

• "Quick fix for now, investigate later"
• "Just try changing X and see"
• "I don't fully understand but this might work"
• "One more fix attempt" (already tried 2+)
• "Let me try a few different things"
• Proposing solutions before gathering evidence
• Skipping failing test case
• Fixing symptoms instead of root cause

<escalation>

1. After 3 failed fix attempts - architecture may be wrong
2. No clear reproduction - need more context/access
3. External system issues - need vendor/team involvement
4. Security implications - need security expertise
5. Data corruption risks - need backup/recovery planning

</escalation> <completion>

• Root cause identified with evidence
• Failing test case created
• Fix addresses root cause only
• Test now passes
• All existing tests pass
• Manual reproduction no longer triggers bug
• No new warnings/errors
• Root cause documented
• Prevention measures considered
• "Verify Fix" marked completed

</completion> <rules>

• Create "Collect Evidence" todo at session start
• Follow four-stage framework
• Update todos on stage transitions
• Create failing test before fix
• Test single hypothesis at a time
• Document root cause after fix
• Mark "Verify Fix" complete only after tests pass

• Propose fixes without understanding root cause
• Skip evidence gathering
• Test multiple hypotheses simultaneously
• Skip failing test case
• Fix symptoms instead of root cause
• Continue after 3 failed fixes without escalation
• Regress stages - add new tasks if needed

</rules> <references>

• playbooks.md - bug-type specific investigations
• evidence-patterns.md - diagnostic techniques
• reproduction.md - reproduction techniques
• integration.md - workflow integration, anti-patterns

</references>

find-root-causes