Debugging Narration

Noticed → Suspected → Tested → Found → Fixed — the five-step debugging narration structure.

Each step explained:
• Noticed: what observable symptom triggered the investigation
• Suspected: initial hypothesis before any investigation
• Tested: what you did to verify or rule out your hypothesis
• Found: the root cause — what was actually wrong
• Fixed: the resolution — what change was made and why

Example:

"I noticed the checkout button was unresponsive on mobile (Noticed).
I suspected a CSS z-index issue was blocking the tap target (Suspected).
I added a pointer-events debug overlay to the element and confirmed taps were being intercepted by the overlay div (Tested).
It turned out the loading spinner was positioned at z-index: 9999 and covering the entire button area even when hidden (Found).
I fixed it by setting display: none on the spinner when it's not active, rather than just opacity: 0 (Fixed)."

Why this structure works:
• Listeners can follow your reasoning
• Shows you investigated rather than guessed
• Conclusion (Found/Fixed) is most important — placed last for emphasis
• Can be shortened for standup: "Noticed X, found it was Y, fixed by doing Z"

Option C — uses past perfect continuous ("had been seeing") and simple past correctly for completed investigations.

Past tense patterns in debugging narration:

Past perfect continuous — for patterns that happened before you investigated:
• "I had been seeing intermittent 503s since Monday"
• "The service had been consuming more memory than usual"
• "Users had been reporting timeouts for two hours"

Simple past — for discrete investigation actions:
• "I checked the logs / I added a breakpoint / I ran the profiler"
• "It turned out that…" — introducing the root cause finding
• "I found that…" / "The issue was…" / "The root cause turned out to be…"

Simple past for fix:
• "I fixed it by changing the timeout to 30s"
• "The fix was to add a retry with exponential backoff"

The phrase "It turned out that…" is essential debugging English — it introduces the finding after the investigation and signals the pivot from hypothesis to confirmed fact.

Option C — "ruled out" + evidence + pivot to next hypothesis.

Phrases for eliminating hypotheses:
• "I ruled out X" — standard investigative English for eliminating a cause
• "X was not the issue" — blunt but acceptable
• "I eliminated X as a cause" — more formal
• "X checked out / looked clean" — informal
• "X was within normal parameters" — metric-based elimination

Why adding evidence is important:
"I ruled out the database" alone is not verifiable. "Query times under 5ms throughout the incident window" gives the team confidence in your conclusion and prevents another engineer from re-investigating the same dead end.

Evidence patterns:
• "CPU was at 12% — ruling out resource exhaustion"
• "The error only appears in EU region — ruling out a global config issue"
• "Bug did not appear on the main branch — ruling out a pre-existing defect"

After ruling out, always name the next focus:
"I then focused on X" / "That led me to investigate Y instead"
This shows a systematic, logical investigation process.

Option B — "It turned out that…" + precise root cause + supporting evidence.

Key phrases for introducing findings:
• "It turned out that…" — most natural; implies discovery after investigation
• "The root cause was…" — direct, formal; used in incident reports
• "I found that…" — simple and clear
• "The issue was…" — common in Slack/standup
• "It was caused by…" — emphasises causation
• "This was traced back to…" — more formal postmortem language

What makes a good root cause statement:
1. Specific component: "the connection pool" not "a pool somewhere"
2. Exact condition: "max pool size was set to 5"
3. Mechanism: "each request opened a new connection without releasing it" — explains HOW the bug occurs
4. Why it wasn't caught: (optional) "no load in staging, so pool was never saturated"

Avoid vague introductions like "probably" or "might be" when you have confirmed the root cause — they undercut confidence in the finding.

Option C — a complete four-element story in three sentences: Symptom → Root Cause → Fix → Deployment status.

Standup debugging story template:

"[What was noticed] → [Root cause (it turned out that)] → [Fix] → [Status/deployment time]"

Example breakdown:
• Noticed: "users getting 500 errors on the payment endpoint"
• Root cause: "null check missing for the coupon code field — crashing when guest checked out without a coupon"
• Fix: "null guard"
• Status: "deployed to prod at 10:48"

Different formats by channel:

Standup (30 seconds): Symptom → Root cause → Fix → Status

Slack thread: Add one sentence on how you found it
"I noticed 500s, checked Sentry, found a null pointer on coupon_code. Added a null check — users without coupons now hit the else branch. Deployed."

Ticket comment: Full Noticed/Suspected/Tested/Found/Fixed structure with code references

Incident report: Timeline with timestamps, full root cause, contributing factors, remediation steps

The key is calibrating the depth of narrative to the audience and communication channel.

Option C — a PR description with Root Cause, Fix, and Regression Test sections.

PR description template for bug fixes:

**Root cause:**
[What was wrong + why it caused the observed behavior]

**Fix:**
[What change was made + why this resolves the root cause]

**Testing:**
[What tests were added or updated to prevent regression]

**Notes:**
[Any caveats, related issues, follow-up work needed]

Why each section matters:
• Root cause: reviewers need to understand WHY the change is correct — without this they cannot assess whether the fix is complete or if it might have side effects
• Fix: describes the logic of the change, not just the diff — "reset the counter to zero on success" explains the intent even if the reviewer doesn't read every line
• Regression test: confirms the bug cannot silently return; shows where to look if it does

Language patterns for PR descriptions:
• "Root cause: X was not doing Y when Z"
• "Fix: added / changed / removed / replaced X with Y"
• "This ensures that…" — connecting the fix to the outcome
• "Regression test in test/X.spec.ts covers the [case] path"
• "Closes #[issue number]" — linking the PR to the bug tracker