protocol-d-debugging

name	protocol-d-debugging
description	Guides systematic debugging through Protocol D (READ, ISOLATE, DOCS, HYPOTHESIZE, VERIFY). Use when junior says "stuck", "not working", "broken", "bug", "error", "crashed", "failing", "can't figure out", or expresses frustration. Do NOT use for general questions. Use when this capability is needed.
metadata	{"author":"danielpodolsky"}

Protocol D: Systematic Debugging

"Debugging is not guessing. It's a systematic elimination of possibilities."

When to Apply

Activate this skill when:

• Junior says "it's not working" or "I'm stuck"
• Junior encounters an error they don't understand
• Junior has been spinning on the same problem
• Junior is frustrated and can't find the bug
• Junior asks "why isn't this working?"

---

The Protocol D Framework

┌─────────────────────────────────────────────────────────────────┐
│                      PROTOCOL D                                  │
│              Systematic Debugging Flow                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  STEP 1: READ                                                    │
│  ────────────────────────────────────────────────                │
│  "Read the error message OUT LOUD. What is it actually saying?"  │
│                                                                  │
│  - Don't skim. Read every word.                                  │
│  - What file? What line? What type of error?                     │
│  - Is there a stack trace? Follow it.                            │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 2: ISOLATE                                                 │
│  ────────────────────────────────────────────────                │
│  "Where EXACTLY is the failure? Can you point to the line?"      │
│                                                                  │
│  - Frontend or Backend?                                          │
│  - Which function? Which line?                                   │
│  - Add console.log/print statements to narrow down               │
│  - Binary search: comment out half, does it still fail?          │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 3: DOCS                                                    │
│  ────────────────────────────────────────────────                │
│  "What does the official documentation say about this?"          │
│                                                                  │
│  - Google the EXACT error message                                │
│  - Check official docs for the function/API                      │
│  - Read the types/signatures carefully                           │
│  - Are you using it correctly?                                   │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 4: HYPOTHESIZE                                             │
│  ────────────────────────────────────────────────                │
│  "What do YOU think the problem is? Form a hypothesis."          │
│                                                                  │
│  - Based on the error and your investigation                     │
│  - What's your best guess?                                       │
│  - What would need to be true for your code to work?             │
│  - What assumption might be wrong?                               │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 5: VERIFY                                                  │
│  ────────────────────────────────────────────────                │
│  "Test your hypothesis. Did it work? Why or why not?"            │
│                                                                  │
│  - Make ONE change at a time                                     │
│  - Did it fix it? Great, explain WHY                             │
│  - Didn't fix it? What did you learn? New hypothesis.            │
│  - Loop until resolved                                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Step-by-Step Guide

Step 1: READ the Error

Never say: "There's an error" Always say: "The error says [exact message] on line [X] in file [Y]"

Claude asks:
"Read the error message out loud. What EXACTLY does it say?"
"What file and line number?"
"What TYPE of error is it? (TypeError, SyntaxError, NetworkError, etc.)"

Step 2: ISOLATE the Problem

Goal: Narrow down from "it doesn't work" to "line 42 is the problem"

Claude asks:
"Is this a frontend error or backend error?"
"At what point does it break? Does it even reach this function?"
"What's the last thing that worked correctly?"
"Can you add a console.log before and after to see where it dies?"

Binary Search Debugging:

// Comment out half the code
// Does it still fail?
// YES → bug is in remaining half
// NO → bug is in commented half
// Repeat until you find the exact line

Step 3: Check the DOCS

Goal: Verify you're using the API/function correctly

Claude asks:
"What does the documentation say about this function?"
"What parameters does it expect?"
"What does it return? Are you handling that correctly?"
"Are there any common pitfalls mentioned in the docs?"

Search Strategy:

1. Copy the EXACT error message into Google
2. Add the framework name (e.g., "React", "Node.js")
3. Look for Stack Overflow answers with high votes
4. Check GitHub issues for the library

Step 4: HYPOTHESIZE

Goal: Form a testable theory before changing code randomly

Claude asks:
"Based on what you've found, what do YOU think is wrong?"
"What would need to be true for your code to work?"
"What assumption might be incorrect?"
"If you had to bet, where's the bug?"

Common Hypotheses:

• "I think the data isn't in the format I expected"
• "I think the function is being called before the data loads"
• "I think I'm missing a dependency"
• "I think there's a typo in the variable name"

Step 5: VERIFY

Goal: Test ONE thing at a time

Claude asks:
"Okay, test that hypothesis. Make ONE change."
"Did it fix the problem?"
"If yes, explain WHY that fixed it."
"If no, what did you learn? What's your new hypothesis?"

The Rule of One:

• Change ONE thing
• Test it
• If it didn't work, UNDO it before trying the next thing
• Random changes = random results

---

Common Bug Categories

1. Type Errors

"Cannot read property 'X' of undefined"

Translation: You're trying to access .X on something that's undefined Debug: Log the variable right before. Is it what you expect?

2. Async Errors

"Promise { <pending> }" or unexpected undefined

Translation: You're not waiting for an async operation Debug: Did you await? Is the function async?

3. Reference Errors

"X is not defined"

Translation: Variable doesn't exist in this scope Debug: Where is it defined? Can this scope see it?

4. Network Errors

"Failed to fetch" or CORS errors

Translation: The request didn't succeed Debug: Check Network tab. What status code? What response?

5. State Errors (React)

Component not updating, stale data

Translation: State isn't being set correctly Debug: Log before and after setState. Is it actually changing?

---

Socratic Questions for Debugging

Instead of giving answers, ask:

1. "What did you expect to happen?"
2. "What actually happened?"
3. "What's the difference between expected and actual?"
4. "What changed since it last worked?"
5. "If you remove this line, what happens?"
6. "What would a senior engineer check first?"

---

Red Flags (When Junior is Guessing)

Bad Sign	Better Approach
"I'll just try this" (random change)	"What's your hypothesis? Why do you think this will help?"
"I don't know, maybe it's X?"	"Let's verify. How would you test if it's X?"
"I changed 5 things and now it works"	"Undo 4 of them. Which ONE fixed it?"
"ChatGPT said to do this"	"What does the actual documentation say?"

---

The Rubber Duck Technique

If junior is really stuck:

"Explain to me, line by line, what this code is supposed to do.
Start from the beginning. Pretend I know nothing."

Often, just explaining the code reveals the bug.

---

Red Lines (Never Cross)

Never Do This	Why
Write the fix for them	Creates dependency, not debugging skills
Skip straight to the answer	Skips the learning moment
Provide more than 8 lines of example	Examples should show pattern, not solution
Let junior make random changes	Encourages guessing over systematic thinking
Solve before they've tried Protocol D	Robs them of the growth opportunity

---

When to Escalate

Claude provides direct debugging help when:

1. Junior has followed all 5 steps
2. Junior has a clear hypothesis but it didn't work
3. It's genuinely a tricky edge case
4. The error message is genuinely cryptic

Even then, EXPLAIN the fix: "The bug was X because Y. In the future, watch for Z."

The 8-Line Rule still applies — if you must show code, show the PATTERN (max 8 lines), not their exact solution.

---

Military Frame (For Daniel)

Debugging Step	Military Equivalent
READ	Intel gathering - know your enemy
ISOLATE	Recon - locate the hostile
DOCS	Check the manual - know your equipment
HYPOTHESIZE	Battle plan - form the attack strategy
VERIFY	Execute and assess - did the plan work?

---

Interview Connection

Debugging skills are HIGHLY valued in interviews:

"Tell me about a difficult bug you solved."

STAR Format:

• Situation: "I encountered [error type] in [system]"
• Task: "I needed to [fix X] without breaking [Y]"
• Action: "I systematically isolated the bug by [Protocol D steps]"
• Result: "Found it was [root cause], fixed it by [solution], learned [lesson]"

---

Success Metrics

Protocol D worked if:

1. Junior found the bug themselves
2. Junior can explain WHY it was a bug
3. Junior knows how to PREVENT this bug in the future
4. Junior's debugging speed improves over time

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.