investigate

Investigate — Root-Cause Debugging

Systematic debugging with mandatory root cause investigation before any code changes.

Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find.

Instructions

Phase 1: Collect Symptoms

Gather all available context before forming any hypothesis.

1. Read the error messages, stack traces, and reproduction steps in full
2. Ask ONE targeted question if the user hasn't provided enough context:
   • "What exact error message do you see?"
   • "Can you reproduce this consistently?"
   • "When did this start happening?"
3. Identify the affected component and its boundaries

Output: A precise symptom statement — what fails, when, with what error.

---

Phase 2: Read the Code

Trace the code path from symptom back to potential causes. Do not guess.

# Find all references to the failing component
grep -rn "ComponentName\|function_name\|error_string" src/ --include="*.{ts,js,py,rb,go}" | head -30

# Check recent changes to affected files
git log --oneline -15 -- <affected-file>

# Read the actual diff for each recent commit
git show <commit-hash> -- <affected-file>

Use Grep to find all references, Read to understand the logic. Never skip reading the code.

---

Phase 3: Check Recent Changes

# What changed recently across the whole repo
git log --oneline -20

# Changes to files related to the symptom
git log --oneline -20 -- <affected-files>

# Full diff of the last N commits
git diff HEAD~3..HEAD -- <affected-directory>

Key question: Was this working before? If yes, the root cause is in the recent diff.

• Regression = root cause is in the changes, not the original code
• Always-broken = architectural issue or incorrect assumption

---

Phase 4: Reproduce

Before fixing anything, confirm you can trigger the bug deterministically.

# Run the test suite targeting the affected area
npm test -- --testPathPattern="affected-module" 2>/dev/null || \
pnpm test -- --testPathPattern="affected-module" 2>/dev/null || \
pytest tests/test_affected.py -v 2>/dev/null

# Check logs if available
tail -50 logs/error.log 2>/dev/null || \
journalctl -u app-service --lines=50 2>/dev/null