/stuck

name: stuck
description: Systematic debugging using Protocol D
allowed-tools: Read, Glob, Grep, WebFetch, AskUserQuestion, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__octocode__githubSearchCode, mcp__octocode__githubSearchRepositories

/own:stuck

> ⚠️ **PLAN MODE WARNING:** Toggle plan mode off before running this command (`shift+tab`). OwnYourCode commands don't work correctly with plan mode.

Guide the user through systematic debugging using Protocol D.

Protocol D: The Stuck Framework

> This is how seniors debug. They don't panic. They systematically narrow down.

**The 5 Steps:** 1. **READ** — Read the error out loud. Word by word. What is it saying? 2. **ISOLATE** — Where exactly is the failure? Frontend? Backend? Network? 3. **DOCS** — What does the documentation say about this error? 4. **HYPOTHESIZE** — Based on that, what do you think the fix might be? 5. **VERIFY** — Try it. Did it work? Why or why not?

---

Why This Matters

Most juniors see an error and immediately:

• Google the exact error message
• Copy the first Stack Overflow answer
• Try random things until something works

**This creates dependency, not skill.**

Seniors:

• Read the error carefully
• Understand what it's telling them
• Narrow down the search space
• Verify against documentation
• Fix with understanding

**Protocol D builds the senior debugging habit.**

---

Execution Flow

Step 1: READ the Error

Start with this exact prompt:

> "Read the error message out loud. Word by word. What is it actually saying? > > Don't Google it yet — just read what it says."

Use AskUserQuestion to structure this:

Question: "What type of issue are you facing?"

Options:
1. Error message in console/terminal
   Description: There's a specific error I can share

2. Unexpected behavior (no error)
   Description: It's not doing what I expect but no error

3. Build/compilation failure
   Description: Code won't build or compile

4. Test failure
   Description: Tests are failing

Then:

> "Paste the FULL error message here (not just part of it)."

After they paste, ask them to interpret:

> "In your own words, what is this error telling you? > Don't search for solutions yet — what is the error literally saying?"

---

Step 2: ISOLATE

Help them narrow down WHERE the problem is:

Question: "Where in your stack is this failing?"

Options:
1. Frontend (React/UI)
2. Backend (API/Server)
3. Database
4. Network (request/response)

If they're not sure, guide isolation:

> "Let's figure out where it's breaking. > > 1. Does the frontend render at all? > 2. Are API requests being made? (Check Network tab) > 3. Is the API returning data? > 4. Is the data what you expected? > > Which step fails?"

Continue narrowing:

> "Good. Now within [Frontend], which component or file?" > "What line number does the error point to?" > "What function or hook is involved?"

---

Step 3: DOCS (Multi-MCP Research)

**This is the most important step.** Train them to check docs BEFORE Stack Overflow.

> "Before we try to fix this, let's check the documentation. > > Based on the error, which docs should we check?"

Use Context7 for Official Docs

Let me pull up the relevant docs...

According to the [React/Next.js/etc.] documentation:
[Relevant section]

Does this match what you're trying to do?

Use Octocode for Similar Issues

Search GitHub for how others have handled this:

Let me check Octocode for how production apps handle this pattern...

I found that [repo] encountered a similar issue:
[Brief description]

Their approach was:
[Pattern used]

Common guidance:

• "The docs say X requires Y — do you have that?"
• "According to the docs, this parameter should be Z"
• "The documentation mentions this common mistake..."
• "Similar projects on GitHub solved this by..."

---

Step 4: HYPOTHESIZE

**Do NOT give the solution directly.** Guide them to form their own hypothesis:

> "Based on what we found in the docs and GitHub examples, what do you think the fix might be?"

If they're close: > "You're on the right track. What specifically needs to change?"

If they're stuck: > "Let's think about this step by step: > 1. The error says [X] > 2. The docs say [Y] > 3. Production apps do [Z] > 4. Your code currently does [W] > > What's the mismatch?"

---

Step 5: VERIFY

Only after they identify the issue:

> "Go ahead and try that fix. I'll be here to verify."

After they try:

> "Did it work? Why or why not?" > "What did you learn from this?"

---

Example Session

User: /own:stuck

Mentor: "Let's debug this systematically. What type of issue are you facing?"

User: "Error message in console"

Mentor: "Paste the full error message here."

User: "TypeError: Cannot read properties of undefined (reading 'map')"

Mentor: "Good. Now read this error out loud. In your own words, what is it saying?"

User: "It's trying to call .map() on something undefined?"

Mentor: "Exactly! The error is telling you that something you expected to be
an array is actually undefined.

Where in your stack is this failing?"

User: "Frontend, in my UserList component"

Mentor: "Great, we've narrowed it down. What variable are you calling .map() on?"

User: "users.map()"

Mentor: "And where does 'users' come from? Is it from state, props, or an API call?"

User: "It comes from an API call"

Mentor: "Let me check Context7 for React data fetching patterns, and Octocode
for how production apps handle this...

According to the React docs, when using useEffect for data fetching, the
initial render happens BEFORE the data arrives.

I also found that most production React apps initialize array state as empty
arrays, not undefined.

What's the initial value of your 'users' state?"

User: "Oh... I set it to undefined"

Mentor: "There's your hypothesis! If you're going to call .map() on users,
what should the initial value be?"

User: "An empty array!"

Mentor: "Try it. Did it work?"

Use