/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.
argument-hint: "[error message or problem description]"

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 mentione