Step 2 · Diagnose

Goal

Find the exact root cause of the bug — the single true source of the wrong behaviour. Not a symptom. Not an approximation. The cause.

Instructions

You are in workflow step 2 of the bug-cycle. The bug is reproducible and a failing test exists. Now find out why it happens.

The Diagnostic Method

You are a detective, not a guesser. Every step of this investigation is:

  1. Form a hypothesis
  2. Gather evidence that proves or disproves it
  3. Eliminate — move to the next hypothesis if disproved
  4. Stop when exactly ONE explanation is consistent with ALL evidence

Tasks to Perform

1. Trace the Code Path

Starting from the reproduction steps, trace through the code from the entry point to where the wrong behaviour occurs:

# Find the entry point (route, command, event handler)
grep -rn "[endpoint or action from reproduction]" \
  --include="*.{php,js,ts,py,go,rb}" . | grep -v node_modules | grep -v vendor | head -20

# Follow the call chain — read each file completely before moving to the next

At each layer ask: Is the data correct here? If yes, the bug is downstream. If no, the bug is here or upstream.

2. Form Three Hypotheses

Write down your three most likely explanations, in order of likelihood:

Hypothesis 1: [The most likely cause]
  → Prediction: [what you'd see if this is true]
  → Test: [what to check]

Hypothesis 2: [Next most likely]
  → Prediction: ...
  → Test: ...

Hypothesis 3: [Less likely but possible]
  → Prediction: ...
  → Test: ...

3. Gather Evidence

For each hypothesis, gather evidence:

Temporary debug output (to be removed after diagnosis):

# Add strategic log statements to narrow down the location
# Run the reproduction steps
# Read the output

Query the database state:

# What does the data look like before and after the operation?
# Is there a constraint violation? An unexpected null? A wrong value?

Check the environment:

# Timezone
# Config values
# Dependency versions
php --version / node --version / python --version
cat composer.json | grep [package] / cat package.json | grep [package]

4. Confirm the Root Cause

You have found the root cause when:

  • You can explain the exact chain of events that produces the wrong behaviour
  • Your explanation is consistent with every piece of evidence
  • Your explanation predicts the behaviour under the reproduction conditions

Write one paragraph here:

Root cause: [Exact file:line] — [What the code does] — [Why that produces the wrong result]

5. Rule Out Related Issues

Once you know the root cause, check:

  • Are there other code paths with the same bug? (search for the same pattern)
  • Are there similar bugs in related features?
grep -rn "[the buggy pattern]" --include="*.{php,js,ts,py,go,rb}" . | grep -v node_modules | grep -v vendor

6. Update TODO.md

Always include the source reference. Status rules: [ ] = not started · [~] = in progress (one at a time) · [x] = done (prefix the date).

## Todo
- [ ] fix: [one-line description] _(ref: workflows/bug-cycle/02-diagnose.md)_
  - Root cause: [file:line — exact explanation]
  - Fix approach: [what to change]
  - Also check: [any related paths with the same problem]

Expected Output

  • Root cause identified and documented
  • Fix approach described in TODO.md
  • Any related affected code paths noted

Exit Criteria

This step is complete when:

  • [ ] Root cause is identified with exact file and line
  • [ ] Root cause can be stated in one sentence
  • [ ] All debug output has been removed (it served its purpose)
  • [ ] Fix approach is written in TODO.md
  • [ ] Ready to proceed to Step 3 (Fix and Verify)