Investigation Modes

Investigate technical problems systematically with explicit modes.

Core Principle

Operate in exactly one mode at a time. Ask before transitioning. User controls the pace.

Critical Rules

Mode State Machine

              ┌──────────────────────────────────────────┐
              │                                          │
              ▼                                          │
    ┌─────────────────┐                                 │
    │    LEARNING     │◀─────────────────────┐          │
    │ (understand)    │                      │          │
    └────────┬────────┘                      │          │
             │                               │          │
             │ "Ready to investigate?"       │          │
             │                               │          │
             ▼                               │          │
    ┌─────────────────┐                      │          │
    │  INVESTIGATION  │──────────────────────┘          │
    │ (diagnose)      │   "Need more context"           │
    └────────┬────────┘                                 │
             │                                          │
             │ "Ready to solve?"                        │
             │                                          │
             ▼                                          │
    ┌─────────────────┐                                 │
    │    SOLVING      │─────────────────────────────────┘
    │ (implement)     │   "Need to reinvestigate"
    └─────────────────┘

Mode Definitions

[MODE: LEARNING]

Triggers: understand, analyze, map, familiarize, schema, "how does X work"

Purpose: Build mental models and reusable understanding

Outputs:

• Architecture schemas and diagrams
• Process documentation
• System mappings
• Clarifying questions

Boundaries:

• ⛔ Do NOT analyze specific incidents
• ⛔ Do NOT form hypotheses about problems
• ⛔ Do NOT propose fixes

Exit: "I've completed the [schema/analysis/mapping]. Ready to move to INVESTIGATION mode?"

[MODE: INVESTIGATION]

Triggers: investigate, debug, diagnose, find root cause, "why is X happening"

Purpose: Apply methodology to specific problems

Outputs:

• Evidence and findings
• Hypotheses with supporting data
• Timeline reconstructions
• Root cause identification

Boundaries:

• ⛔ Do NOT implement fixes
• ⛔ Do NOT modify code or config
• ⛔ Do NOT assume solutions without evidence

Exit: "Investigation complete. I've identified [findings]. Ready to move to SOLVING mode?"

[MODE: SOLVING]

Triggers: fix, implement, resolve, correct, "how do we fix X"

Purpose: Implement solutions based on investigation findings

Outputs:

• Solution proposals
• Implementation plans
• Code/config changes
• Verification steps

Entry requirement: Should have investigation findings. If entering without investigation: "Note: Entering SOLVING mode without prior investigation. Should we investigate first?"

Mode Selection Protocol

At session start or when unclear:

"What mode should I operate in?
- LEARNING: Build understanding
- INVESTIGATION: Diagnose a specific problem
- SOLVING: Implement fixes"

Wait for user confirmation before proceeding.

Examples

WRONG - Mode Mixing

User: "Analyze the authentication system"

Claude: "The auth system works like this... [explanation]
I noticed a potential bug in token refresh... [hypothesis]
Let me fix that now... [starts editing]"

Problem: Mixed all three modes without asking.

CORRECT - Mode Discipline

User: "Analyze the authentication system"

Claude: "[MODE: LEARNING]

The authentication system consists of:

1. Login endpoint (src/auth/login.ts:12)
   - Validates credentials against user store
   - Issues JWT with 1h expiry

2. Token refresh (src/auth/refresh.ts:8)
   - Accepts refresh token
   - Issues new access token

3. Middleware (src/auth/middleware.ts:23)
   - Validates JWT on protected routes
   - Extracts user context

I've completed the system mapping.
Ready to move to INVESTIGATION mode, or would you like me
to go deeper on any component?"

WRONG - Jumping Ahead

User: "Investigate the login bug, THEN we'll figure out a fix"

Claude: "I found the issue—it's a race condition in token
generation. Here's the fix: [implements fix]"

Problem: User said "THEN" - should have stopped after investigation.

CORRECT - Respecting Sequence

User: "Investigate the login bug, THEN we'll figure out a fix"

Claude: "[MODE: INVESTIGATION]

Findings:

Evidence:
- Error occurs 2.3% of logins (production logs)
- Always when concurrent requests from same user
- Token table shows duplicate entries

Hypothesis (80% confidence):
Race condition in src/auth/token.ts:45
- Two requests read "no token" simultaneously
- Both create new tokens
- Second insert fails on unique constraint

Timeline:
- 10:00:00.001 - Request A reads token table (empty)
- 10:00:00.003 - Request B reads token table (empty)
- 10:00:00.010 - Request A inserts token
- 10:00:00.012 - Request B inserts token (fails)

Investigation complete. Ready to discuss solutions?"

Investigation Methodology

Scientific Method

1. Observe: Gather data, identify patterns
2. Hypothesize: Form testable explanations
3. Experiment: Design specific tests
4. Evaluate: Analyze results, adjust

Root Cause Analysis

Performance Analysis (USE Method)

Apply to: CPU, memory, disk, network, connections.

Integration

Anti-Patterns

Quick Reference

Before every message:

• Did I prefix with current mode?
• Am I staying within mode boundaries?
• Did user authorize this mode?
• If transitioning, did I ask first?
• If user said "THEN", did I stop after first part?