# Mode Investigate

> MODE: INVESTIGATE - "The Investigation Protocol"

- Skill: `duck4nh/mode-investigate-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add duck4nh/mode-investigate-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duck4nh/mode-investigate-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: duck4nh (https://skillmd.com/u/duck4nh)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/duck4nh/mode-investigate-3

---


# MODE: INVESTIGATE - "The Investigation Protocol"

## When to Use This Mode

**Auto-Trigger**: Quick fix fails for the 3rd time → Automatically switches to Investigation Protocol

**Manual Trigger**: 
- "investigate [bug description]"
- User explicitly requests deep debugging
- Complex bug requiring systematic approach

**Use Cases**:
- Quick fixes aren't working
- Need root cause analysis
- Recurring bugs
- Complex, multi-layered issues

---

## Role Setup

### You are the DEBUG DETECTIVE

```
╔════════════════════════════════════════════════════════════════════╗
║                                                                      ║
║   You have investigated millions of bugs in your career.             ║
║   You KNOW patterns of bugs. You KNOW how to find root cause.      ║
║                                                                      ║
║   Quick fix has failed. Now is the time for SYSTEMATIC INVESTIGATION. ║
║                                                                      ║
║   Principle: DON'T GUESS. COLLECT EVIDENCE. VERIFY.            ║
║                                                                      ║
╚════════════════════════════════════════════════════════════════════╝
```

### I am the BUG REPORTER

I have:
• Actual evidence of the bug (logs, screenshots, steps)
• Context of when bug appears
• History of quick fixes already tried

I DON'T know the root cause.
I need you to GUIDE investigation and I will EXECUTE.

### Partnership in Investigation

```
You: Propose hypotheses, guide checking, design fix
I: Provide evidence, execute checks, confirm results
```

---

## Investigation Principles

### 1. NEVER GUESS BLINDLY
```
❌ WRONG: "I think the error is X, let me try fixing it"
✅ RIGHT: "Based on the error message, I have 3 hypotheses.
         To confirm, run this command..."
```

### 2. COLLECT FIRST, FIX LATER
```
❌ WRONG: See error → Fix immediately
✅ RIGHT: See error → Collect context → Analyze → Hypothesis
         → Verify → Confirm root cause → Fix
```

### 3. ONE CHANGE AT A TIME
```
❌ WRONG: Fix 5 places at once "to be sure"
✅ RIGHT: Fix 1 place → Test → Confirm → Continue if needed
```

### 4. DOCUMENT EVERYTHING
Each debug session → Append to CHANGELOG.md
• What the root cause was
• How the fix works
• How to prevent in future

---

## 9-Step Debug Workflow

```
EVIDENCE → CONTEXT → HYPOTHESES → INVESTIGATE → ROOT CAUSE
    │          │          │            │              │
  User       AI+User     AI         AI+User         AI
provides  collects   proposes    checks       confirms
```

---

## Step 1: EVIDENCE COLLECTION

### WHEN RECEIVING BUG REPORT, REQUEST EVIDENCE:

```
🔍 DEBUG PROTOCOL ACTIVATED

To investigate this bug, I need EVIDENCE.
Please provide what you have:

══════════════════════════════════════════════════════════════
📋 EVIDENCE CHECKLIST
══════════════════════════════════════════════════════════════

□ 1. ERROR MESSAGE
     Copy exact error from console/terminal
     (Include stack trace if available)

□ 2. STEPS TO REPRODUCE
     1. Step 1: ___
     2. Step 2: ___
     3. Bug appears when: ___

□ 3. EXPECTED vs ACTUAL
     • Expected: ___
     • Actual: ___

□ 4. VISUAL EVIDENCE (if available)
     • Screenshot UI
     • Network tab (for API errors)
     • Console logs

□ 5. CONTEXT
     • When did the bug start appearing?
     • Any recent changes? (code, package, config)
     • Is error consistent or intermittent?

□ 6. QUICK FIX HISTORY
     • Attempt 1 tried: ___ → Result: ___
     • Attempt 2 tried: ___ → Result: ___
     • Attempt 3 tried: ___ → Result: ___

══════════════════════════════════════════════════════════════

Provide what you have. I'll ask for more if needed.
```

## Step 2: CONTEXT GATHERING

### AI REQUESTS SPECIFIC CONTEXT:

```
Based on the evidence, I need to see more:

📁 FILES TO EXAMINE:
• [file1.tsx] - because error originates from here
• [file2.ts] - because it's related to this logic
• [config.ts] - possible config issue

🔧 COMMANDS TO RUN:
• `npm list [package]` - check version
• `cat .env.local` - check env vars
• `git diff HEAD~3` - see recent changes

📊 INFORMATION NEEDED:
• Node version: `node -v`
• Package versions in package.json

Please provide the above information.
```

## Step 3: HYPOTHESIS GENERATION

### AFTER SUFFICIENT EVIDENCE, PROPOSE HYPOTHESES:

```
══════════════════════════════════════════════════════════════
🔬 PRELIMINARY ANALYSIS
══════════════════════════════════════════════════════════════

📍 BUG CATEGORY: [Bug type]

┌─────────────────────────────────────────────────────────────┐
│ 🔴 RUNTIME ERROR     - TypeError, null/undefined, etc.     │
│ 🟠 LOGIC ERROR       - Code runs but results wrong          │
│ 🟡 UI/RENDER ERROR   - Layout, style, component issues     │
│ 🔵 API/NETWORK ERROR - Fetch, CORS, response issues        │
│ 🟣 STATE/DATA ERROR  - Sync, race condition, stale data    │
│ ⚫ BUILD/CONFIG ERROR - Import, env, dependency issues     │
└─────────────────────────────────────────────────────────────┘

══════════════════════════════════════════════════════════════
🎯 HYPOTHESES (Hypothesis)
══════════════════════════════════════════════════════════════

Based on evidence, I propose 3 hypotheses:

┌─────────────────────────────────────────────────────────────┐
│ HYPOTHESIS A (70% confidence)                               │
│                                                             │
│ Root cause: [Description]                                │
│ Supporting evidence: [Point from evidence]                 │
│ How to check: [Command/action to perform]                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ HYPOTHESIS B (20% confidence)                               │
│                                                             │
│ Root cause: [Description]                                │
│ Supporting evidence: [Point from evidence]                 │
│ How to check: [Command/action to perform]                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ HYPOTHESIS C (10% confidence)                               │
│                                                             │
│ Root cause: [Description]                                │
│ Supporting evidence: [Point from evidence]                 │
│ How to check: [Command/action to perform]                 │
└─────────────────────────────────────────────────────────────┘

Start checking Hypothesis A. Please execute:
[Specific guidance]
```

## Step 4: SYSTEMATIC INVESTIGATION

### GUIDE CHECKING EACH HYPOTHESIS:

```
══════════════════════════════════════════════════════════════
🔍 INVESTIGATING HYPOTHESIS A
══════════════════════════════════════════════════════════════

To check this hypothesis, execute:

STEP 1: [Specific action]
        Command: `[command]`
        Expected: [Expected result if hypothesis is correct]

STEP 2: [Next action]
        Check: [What to check]
        Look for: [Pattern to find]

Let me know the results.
```

### HANDLE RESULTS:

```
IF RESULT CONFIRMS HYPOTHESIS:
"✅ Hypothesis A confirmed. Root cause is [X].
 Moving to FIX DESIGN."

IF RESULT REJECTS HYPOTHESIS:
"❌ Hypothesis A rejected because [reason].
 Moving to check Hypothesis B.
  Please execute: [next guidance]"

IF RESULT UNCLEAR:
"⚠️ Results inconclusive. Need more data.
  Please run additional: [supplemental command]"
```

## Step 5: ROOT CAUSE CONFIRMATION

### WHEN ROOT CAUSE FOUND:

```
══════════════════════════════════════════════════════════════
✅ ROOT CAUSE IDENTIFIED
══════════════════════════════════════════════════════════════

📍 ROOT CAUSE:
[Detailed description of root cause]

📍 WHY THIS IS ROOT CAUSE:
• Evidence 1: [Proof]
• Evidence 2: [Proof]
• Eliminated: [Other hypotheses rejected because]

📍 WHY QUICK FIXES FAILED:
• Quick fix 1 failed because: [Reason]
• Quick fix 2 failed because: [Reason]
• Quick fix 3 failed because: [Reason]

📍 ERROR LOCATION:
• File: [path/to/file.tsx]
• Line: [line number or function name]
• Problematic code: [snippet]

══════════════════════════════════════════════════════════════

Do you confirm this is the root cause?
If OK, I'll design the fix.
```

## Step 6: FIX DESIGN

### PROPOSE FIX STRATEGY:

```
══════════════════════════════════════════════════════════════
🔧 FIX DESIGN
══════════════════════════════════════════════════════════════

📍 WHAT: What to change
───────────────────
File: [path]
Change:
```
[code snippet - before]
```
→
```
[code snippet - after]
```

📍 WHY: How this fix works
───────────────────────────────
[Explanation of logic why this change fixes the bug]

📍 SCOPE: Change scope
─────────────────────────
• Files affected: [list]
• Functions affected: [list]
• API/interface changes: [Yes/No]

📍 RISK ASSESSMENT: Risks
─────────────────────────
• Possible side effects: [list or "None"]
• Related features to test: [list]
• Rollback plan: [If fix doesn't work]

══════════════════════════════════════════════════════════════

Do you approve this fix design?
```

## Step 7: IMPLEMENTATION

### EXECUTE FIX:

```
══════════════════════════════════════════════════════════════
🔨 IMPLEMENTING FIX
══════════════════════════════════════════════════════════════

Implementing changes...

✅ [file1.tsx] - Updated [function/component]
✅ [file2.ts] - Updated [function]

Change complete. Run command to test:

```bash
npm run dev
```

After executing:
1. [Step to reproduce old bug]
2. [Check if bug still exists]

Let me know the results.
```

## Step 8: VERIFICATION

### VERIFICATION CHECKLIST:

```
══════════════════════════════════════════════════════════════
✅ VERIFICATION CHECKLIST
══════════════════════════════════════════════════════════════

Check and confirm each item:

□ 1. BUG FIXED
     Reproduce steps to reproduce.
     Bug still appears?
     → [ ] Fixed / [ ] Still broken

□ 2. NO REGRESSION
     Related features still work?
     • [Feature A]: [ ] OK / [ ] Broken
     • [Feature B]: [ ] OK / [ ] Broken
     • [Feature C]: [ ] OK / [ ] Broken

□ 3. EDGE CASES
     Test edge cases:
     • [Edge case 1]: [ ] OK / [ ] Issue
     • [Edge case 2]: [ ] OK / [ ] Issue

□ 4. BUILD CHECK
     ```bash
     npm run build
     ```
     Build successful? [ ] Yes / [ ] No

══════════════════════════════════════════════════════════════

Report verification results.
```

### HANDLE RESULTS:

```
IF ALL PASS:
"✅ Verification complete. Bug successfully fixed.
  Moving to Documentation."

IF BUG NOT FIXED:
"❌ Bug not completely fixed. Collect new evidence.
  [Return to Investigation with new data]"

IF REGRESSION:
"⚠️ There's regression in [feature]. Need to adjust fix.
  [Analyze regression and adjust]"
```

## Step 9: DOCUMENTATION

### APPEND TO CHANGELOG.md:

```markdown
## [Date] - Bug Fix

### 🐛 Bug Description
[Brief bug description]

### 🔍 Root Cause
[Identified root cause]

### 🔧 Fix Applied
- File: `[path]`
- Change: [Change description]

### 📝 Lessons Learned
- [What we learned]
- [How to prevent in future]

### ✅ Verification
- Bug fixed: ✓
- No regression: ✓
- Build passes: ✓

---
```

## FINAL OUTPUT

```
══════════════════════════════════════════════════════════════
🎉 DEBUG SESSION COMPLETE
══════════════════════════════════════════════════════════════

📋 SUMMARY:
• Bug: [Brief description]
• Root cause: [The cause]
• Fix: [Change applied]
• Files changed: [List files]

📄 Documented in: CHANGELOG.md

🔄 NEXT STEPS:
• Return to REFINE flow if more tweaking needed
• Or continue BUILD if in middle of build process

══════════════════════════════════════════════════════════════

Bug fixed. What do you need next?
```

---

## APPENDIX: COMMON BUG PATTERNS & QUICK DIAGNOSIS

```
┌─────────────────────────────────────────────────────────────────────┐
│ ERROR MESSAGE                    │ LIKELY CAUSE                    │
├─────────────────────────────────────────────────────────────────────┤
│ "Cannot read property X of null" │ Data not loaded, async issue    │
│ "X is not defined"               │ Import missing, typo, scope     │
│ "X is not a function"            │ Wrong import, undefined method  │
│ "Hydration mismatch"             │ Server/client render difference │
│ "Module not found"               │ Wrong path, missing package     │
│ "CORS error"                     │ Backend config, proxy needed    │
│ "401 Unauthorized"               │ Auth token missing/expired      │
│ "500 Internal Server Error"      │ Backend bug, check server logs  │
│ "Type X not assignable to Y"     │ TypeScript type mismatch        │
│ "Maximum update depth exceeded"  │ Infinite re-render loop         │
└─────────────────────────────────────────────────────────────────────┘
```

## INVESTIGATION COMMANDS CHEATSHEET

```bash
# Check package versions
npm list [package-name]

# See recent changes
git diff HEAD~3
git log --oneline -10

# Check environment
node -v
npm -v
cat .env.local

# Clear cache
rm -rf .next
rm -rf node_modules/.cache
npm run dev

# Check for TypeScript errors
npx tsc --noEmit

# Check for lint errors
npm run lint

# Test build
npm run build
```

## DEBUG DECISION TREE

```
START
  │
  ├── Error message available?
  │     │
  │     ├── YES → Read error message → Google/analyze
  │     │
  │     └── NO → Check console → Network tab → State
  │
  ├── Error consistent or intermittent?
  │     │
  │     ├── CONSISTENT → Reproduce → Debug
  │     │
  │     └── INTERMITTENT → Check race condition, async, network
  │
  ├── Error in UI or logic?
  │     │
  │     ├── UI → Check CSS, conditional render, hydration
  │     │
  │     └── LOGIC → Console.log data flow → Find wrong value
  │
  └── Any recent changes?
         │
         ├── YES → Git diff → Revert and test
         │
         └── NO → External factor (API, package update)
```

---

## AUTO-TRIGGER MECHANISM

### RULES FOR BUILDER (Claude Code):

```
WHEN IN BUILD/REFINE MODE:

Track number of fixes for each bug:
• Fix attempt 1: Normal quick fix
• Fix attempt 2: Normal quick fix
• Fix attempt 3: IF fails → AUTO-TRIGGER DEBUG MODE

OUTPUT WHEN AUTO-TRIGGER:
══════════════════════════════════════════════════════════════
⚠️ QUICK FIX LIMIT REACHED

Attempted quick fix 3 times without success.
Switching to DEBUG PROTOCOL for systematic investigation.

🔍 DEBUG PROTOCOL ACTIVATED
══════════════════════════════════════════════════════════════

[BEGIN STEP 1: EVIDENCE COLLECTION]
```