Agent skill

protocol-d-debugging

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.

View SKILL.md on GitHub Repository
Stars 155
Forks 11

Install this agent skill to your Project

npx add-skill https://github.com/DanielPodolsky/ownyourcode/tree/main/.claude/skills/fundamentals/debugging

SKILL.md

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:

typescript
// 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

DanielPodolsky/ownyourcode

resume-bullet-extraction

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.

155 11
Explore
DanielPodolsky/ownyourcode

star-story-extraction

Transforms completed work into STAR interview stories (Situation, Task, Action, Result). Use when completing tasks, preparing for behavioral interviews, or documenting achievements.

155 11
Explore
DanielPodolsky/ownyourcode

testing-gate

Verifies test coverage and encourages testing habits. WARNING gate that checks for tests during /own:done flow without blocking.

155 11
Explore
DanielPodolsky/ownyourcode

ownership-gate

Verifies junior truly understands code they wrote through line-by-line walkthrough. BLOCKING gate that must pass to complete any task. Triggered during /own:done flow.

155 11
Explore
DanielPodolsky/ownyourcode

error-handling-gate

Verifies error handling including empty catch detection, user-friendly messages, and logging. WARNING gate triggered during /own:done flow.

155 11
Explore
DanielPodolsky/ownyourcode

security-gate

Verifies security before merge/deploy including OWASP Top 10, input validation, and auth checks. WARNING gate triggered during /own:done flow.

155 11
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results