// 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.
Transforms completed work into powerful resume bullet points with action verbs, technical context, and quantified impact. Use when completing tasks, updating portfolio, or preparing job applications.
Transforms completed work into STAR interview stories (Situation, Task, Action, Result). Use when completing tasks, preparing for behavioral interviews, or documenting achievements.
Reviews accessibility including WCAG, ARIA, keyboard navigation. Use when junior builds forms, buttons, modals, interactive elements, or asks "is this accessible", "a11y", "screen reader".
Reviews API design, REST conventions, and backend architecture. Use when junior builds API endpoints, Express routes, middleware, controllers, or asks "is this RESTful", "check my endpoint".
Reviews schema design, SQL queries, ORM patterns. Use when junior creates schema, writes queries, adds migrations, works with Prisma/MongoDB/PostgreSQL, or asks "is this SQL safe", "N+1", "index".
Guides documentation standards including READMEs, JSDoc, and code comments. Use when writing documentation, adding comments, or explaining code. Enforces "WHY not WHAT" principle.
| 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] |
"Debugging is not guessing. It's a systematic elimination of possibilities."
Activate this skill when:
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────────────┘
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.)"
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
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:
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:
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:
"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?
"Promise { <pending> }" or unexpected undefined
Translation: You're not waiting for an async operation
Debug: Did you await? Is the function async?
"X is not defined"
Translation: Variable doesn't exist in this scope Debug: Where is it defined? Can this scope see it?
"Failed to fetch" or CORS errors
Translation: The request didn't succeed Debug: Check Network tab. What status code? What response?
Component not updating, stale data
Translation: State isn't being set correctly Debug: Log before and after setState. Is it actually changing?
Instead of giving answers, ask:
| 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?" |
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.
| 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 |
Claude provides direct debugging help when:
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.
| 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? |
Debugging skills are HIGHLY valued in interviews:
"Tell me about a difficult bug you solved."
STAR Format:
Protocol D worked if: