Diagnosis Protocol

Structured root cause analysis methodology. Replaces ad-hoc guessing with evidence-based investigation.

Core Principle

NEVER guess root causes. Form hypotheses through structured reasoning and test them against evidence.

Pre-Diagnosis: Capture State (MANDATORY)

Before any investigation, capture the current broken state as baseline:

1. Record exact error messages (copy-paste, not paraphrase)
2. Record failing test output (full command + output)
3. Record relevant stack traces
4. Record relevant log snippets with timestamps
5. Record git status / recent changes: git log --oneline -10

This baseline is required for Step 5 (Verify) — you MUST compare before/after.

Diagnosis Chain (Follow in Order)

Phase 1: Observe — What is actually happening?

Read, don't assume. Use ck:debug (systematic-debugging Phase 1).

What is the exact error message?
Where does it occur? (file, line, function)
When did it start? (check git log, git bisect)
Can it be reproduced consistently?
What is the expected vs actual behavior?

Phase 2: Hypothesize — Why might this happen?

Activate ck:sequential-thinking skill. Form hypotheses through structured reasoning.

Structured hypothesis formation:

For each hypothesis:
  1. State the hypothesis clearly
  2. What evidence would CONFIRM it?
  3. What evidence would REFUTE it?
  4. How to test it quickly?

Common hypothesis categories:

Recent code change introduced regression (git log, git diff)
Data/state mismatch (wrong input, stale cache, race condition)
Environment difference (deps version, config, platform)
Missing validation (null check, type guard, boundary)
Incorrect assumption (API contract, data shape, ordering)

Phase 3: Test — Verify hypotheses against evidence

Spawn parallel Explore subagents to test each hypothesis simultaneously:

// Launch in SINGLE message — max 3 parallel agents
Task("Explore", "Test hypothesis A: [specific search/check]", "Verify H-A")
Task("Explore", "Test hypothesis B: [specific search/check]", "Verify H-B")
Task("Explore", "Test hypothesis C: [specific search/check]", "Verify H-C")

For each hypothesis result:

CONFIRMED: Evidence supports this as root cause → proceed to root cause tracing
REFUTED: Evidence contradicts → discard, note why
INCONCLUSIVE: Need more data → refine hypothesis or gather more evidence

Phase 4: Trace — Follow the root cause chain

Use ck:debug (root-cause-tracing technique). Trace backward:

Symptom (where error appears)
  ↑ Immediate cause (what triggered the error)
    ↑ Contributing factor (what set up the bad state)
      ↑ ROOT CAUSE (the original trigger that must be fixed)

Rule: NEVER fix where the error appears. Trace back to the source.

Phase 5: Escalate — When hypotheses fail

If 2+ hypotheses are REFUTED:

Auto-activate ck:problem-solving skill
Apply Inversion Exercise: "What would CAUSE this bug intentionally?"
Apply Scale Game: "Does this fail with 1 item? 100? 10000?"
Consider environmental factors (timing, concurrency, platform)

If 3+ fix attempts fail after diagnosis:

STOP immediately
Question the architecture — is the design fundamentally flawed?
Discuss with user before attempting more

Diagnosis Report Format

## Diagnosis Report

**Issue:** [one-line description]
**Pre-fix state captured:** Yes/No

### Root Cause
[Clear explanation of the root cause, traced back to origin]

### Evidence Chain
1. [Observation] → led to hypothesis [X]
2. [Test result] → confirmed/refuted [X]
3. [Trace] → root cause at [file:line]

### Affected Scope
- Files: [list]
- Functions: [list]
- Dependencies: [list]

### Recommended Fix
[What to change and why — addressing root cause, not symptoms]

### Prevention Needed
[What guards/tests to add to prevent recurrence]

Quick Mode Diagnosis

For trivial issues (type errors, lint, syntax), abbreviated diagnosis:

Read error message
Locate affected file(s) via scout results
Identify root cause (usually obvious for simple issues)
Skip parallel hypothesis testing
Still capture pre-fix state for verification

4.1 KiB Raw Blame History