/dog:investigate — Evidence-First Bug Investigation

Structured protocol that forces evidence collection before any code is written. Prevents the most common debugging failure: fixing symptoms instead of causes.

When to Use

• Any bug or test failure
• Unexpected behavior with unclear root cause
• Performance regressions
• Flaky tests

When NOT to Use

• Typos or trivial one-liner fixes where the cause is already obvious
• Documentation changes

The Protocol

INVESTIGATE → collect evidence (NO code edits)
    ↓
ANALYZE → identify candidates with estimated probability
    ↓
HYPOTHESIZE → write a confirmation test that would fail if hypothesis is wrong; run it
    ↓
IMPLEMENT → only after confirmation test passes

Red flag: If you wrote code before Phase 4, you skipped the protocol.

---

Phase 1 — INVESTIGATE (evidence collection)

Goal: Understand exactly what is failing and why.

Actions:

• Collect the full error message and stack trace
• Reproduce the failure with the minimal repro case
• Read the relevant code without editing it
• Collect relevant logs, metrics, or test output

Tools allowed: Read, Grep, Glob, Bash (read-only commands only)

Code edits: PROHIBITED in this phase.

Output: A written summary of the evidence:

## Evidence
- Error: [exact error message]
- Repro: [minimal repro steps]
- Affected files: [list]
- Related code: [file:line references]
- Logs: [relevant excerpts]

---

Phase 2 — ANALYZE (candidate identification)

Goal: List all plausible root causes with estimated probabilities.

Actions:

• List 2-5 candidate hypotheses
• Assign estimated probability (HIGH / MEDIUM / LOW) to each
• Explain why each candidate is or isn't the most likely cause

Output:

## Candidates
1. [Description] — HIGH (reason: ...)
2. [Description] — MEDIUM (reason: ...)
3. [Description] — LOW (reason: ...)

Pick the highest-probability candidate to test first.

---

Phase 3 — HYPOTHESIZE (confirmation test)

Goal: Write a test that would fail if the hypothesis is correct, then run it to confirm.

Actions:

1. Write a minimal test (unit or integration) that directly probes the suspected root cause
2. Run it — if it fails, the hypothesis is confirmed; if it passes, go back to Phase 2
3. Do NOT fix the bug yet — only confirm the hypothesis

Example:

def test_confirms_hypothesis():
    # This test should FAIL if our hypothesis is right
    result = the_buggy_function(edge_case_input)
    assert result == expected_value  # fails → hypothesis confirmed

Run the test:

pytest tests/test_confirms_hypothesis.py -v
# Expected: FAIL (1 failed) — hypothesis confirmed

Only proceed to Phase 4 after the confirmation test fails as expected.

---

Phase 4 — IMPLEMENT (fix)

Goal: Fix the confirmed root cause, then verify the confirmation test passes.

Actions:

1. Implement the minimal fix for the confirmed root cause
2. Run the confirmation test — it must now pass
3. Run the full test suite to check for regressions
4. If regressions appear, do NOT ship — return to Phase 2

Verification:

pytest tests/test_confirms_hypothesis.py -v  # now PASS
pytest                                        # full suite — no new failures

---

Verification

A complete investigation produces:

1. Written evidence summary (Phase 1)
2. Candidate list with probabilities (Phase 2)
3. A confirmation test that first failed, then passed (Phases 3+4)
4. Full test suite green after the fix

Related

• Skill: dog:systematic-debugging, dog:test-driven-development
• Command: /dog:systematic-debugging, /dog:tdd
• Agent: code-reviewer