DIAGNOSE Framework — 7-Phase Debugging Protocol

Dev Trilogy

CONSTRUCT

→

DEPLOY

→

DIAGNOSE

⚡

Root Cause First: The most expensive bug is the one you fix twice because you misdiagnosed it.

Define the Symptom Exactly

Write one precise sentence describing what's wrong. "It's broken" is not a symptom. "The dashboard returns a 500 on /api/scores when date filter is applied" is.

Precision
First

Isolate the Scope

Is this one endpoint, one feature, or everything? Narrow the blast radius before touching any code. Scope determines strategy.

Contain
First

Audit What Changed

What was the last thing that deployed? Check git log, dependency updates, environment changes. Bugs don't appear randomly, something changed.

Change
Log

Generate Hypotheses

List 3 possible causes ranked by likelihood. Don't test yet. Thinking before touching prevents the trap of fixing the wrong thing confidently.

Think
First

Narrow with Evidence

Test your highest-probability hypothesis with the minimum change needed to confirm or eliminate it. One variable at a time. Logs tell the truth.

Test
One Thing

Override with the Fix

Implement the confirmed fix. Not a patch, the actual solution. If you don't understand why it works, you don't have a fix yet.

Real
Fix Only

Seal with Prevention

Document root cause, fix applied, and what would catch this earlier next time. Every bug is information about the system. Capture it or repeat it.

Close
the Loop

Exit Through Verification

Test the original symptom. Test adjacent features. Confirm you fixed the bug without introducing a new one. Don't close the ticket until production confirms it.

Confirm
in Prod

The final piece of the trilogy

DIAGNOSE completes the development lifecycle: CONSTRUCT builds it, DEPLOY ships it, DIAGNOSE fixes it when something goes wrong. And something always goes wrong.

The framework's most counterintuitive step is Phase 4: "Generate Hypotheses." When something's broken in production, every instinct says to start changing code immediately. DIAGNOSE says stop and think first. List three possibilities, rank them, then test the most likely one with the smallest possible change. This prevents the common trap of confidently fixing the wrong thing.

Phase 7, "Seal with Prevention," is what separates debugging from diagnosis. Fixing the bug solves today's problem. Documenting the root cause and adding prevention solves it permanently. Every bug you encounter is teaching you something about your system. The question is whether you're listening.