Agent skill
stuck
Get unstuck when blocked on a problem. Use when you've tried multiple approaches without success, or when debugging has hit a wall.
Install this agent skill to your Project
npx add-skill https://github.com/johnlindquist/claude/tree/main/skills/stuck
SKILL.md
Stuck Helper
Systematic approaches for getting unstuck on hard problems.
When to Use
- You've tried multiple approaches without success
- The same error keeps appearing despite fixes
- You don't understand why something isn't working
- Debugging has hit a dead end
Quick Unstuck
gemini -m pro -o text -e "" "I'm stuck on this problem:
PROBLEM: [describe what you're trying to do]
TRIED: [what you've already attempted]
ERROR/SYMPTOM: [what's happening]
EXPECTED: [what should happen]
Help me get unstuck. Consider:
1. Am I solving the right problem?
2. What assumptions might be wrong?
3. What haven't I tried?
4. What would an expert check first?"
Structured Debugging
Rubber Duck Protocol
gemini -m pro -o text -e "" "I need to rubber duck debug this issue:
I'm trying to: [goal]
The code does: [behavior]
I expected: [expected behavior]
The relevant code is:
\`\`\`
[paste code]
\`\`\`
Walk through the code step by step with me, questioning each assumption."
Assumption Audit
gemini -m pro -o text -e "" "Audit my assumptions about this problem:
PROBLEM: [description]
MY ASSUMPTIONS:
1. [assumption 1]
2. [assumption 2]
3. [assumption 3]
For each assumption:
- Is it definitely true?
- How would I verify it?
- What if it's wrong?"
Fresh Perspective
gemini -m pro -o text -e "" "I've been stuck on this for a while. Give me a completely fresh approach:
PROBLEM: [description]
WHAT I'VE TRIED:
- [approach 1]
- [approach 2]
- [approach 3]
Suggest approaches from a different angle. What would someone with no context try?"
Common Stuck Scenarios
Async/Promise Issues
gemini -m pro -o text -e "" "Debug this async code issue:
CODE:
\`\`\`
[paste async code]
\`\`\`
SYMPTOM: [what's happening]
Check for:
- Missing await
- Race conditions
- Unhandled rejections
- Callback timing
- Promise chain issues"
State Management
gemini -m pro -o text -e "" "Debug this state management issue:
FRAMEWORK: [React/Vue/etc]
CODE:
\`\`\`
[paste code]
\`\`\`
SYMPTOM: State not updating / Stale state / Infinite loop
Check for:
- Mutation vs immutable update
- Dependency arrays
- Closure over stale values
- Re-render triggers"
Type Errors
gemini -m pro -o text -e "" "Help me understand this TypeScript error:
ERROR:
\`\`\`
[paste error]
\`\`\`
CODE:
\`\`\`
[paste code]
\`\`\`
Explain:
1. What the error means in plain English
2. Why TypeScript is complaining
3. How to fix it properly (not just any)"
Build/Config Issues
gemini -m pro -o text -e "" "Debug this build/config issue:
TOOL: [webpack/vite/esbuild/etc]
ERROR:
\`\`\`
[paste error]
\`\`\`
CONFIG:
\`\`\`
[paste config]
\`\`\`
Common causes and solutions for this type of error."
Escalation Ladder
When simple debugging fails, escalate systematically:
Level 1: Verify Environment
# Check versions
node --version
npm --version
# Check dependencies
npm ls
# Clean and reinstall
rm -rf node_modules package-lock.json && npm install
Level 2: Minimal Reproduction
# Create minimal test case
mkdir /tmp/test-issue
cd /tmp/test-issue
# Create smallest code that reproduces issue
Level 3: Git Bisect
# Find when it broke
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Test each commit git suggests
Level 4: Search for Similar Issues
# GitHub issues
gh search issues "[error message]" --limit 10
# With specific repo
gh search issues "[error]" --repo package/repo
Level 5: Ask for Help
# Prepare a good question
gemini -m pro -o text -e "" "Help me write a good Stack Overflow question for:
PROBLEM: [description]
CODE: [minimal reproduction]
ERROR: [full error]
TRIED: [what I've attempted]
Format as a clear, answerable question."
Prevention Checklist
After getting unstuck, prevent recurrence:
gemini -m pro -o text -e "" "I just solved this issue:
PROBLEM: [what was wrong]
SOLUTION: [how I fixed it]
Suggest:
1. Test to prevent regression
2. Documentation to add
3. Linting/tooling to catch this earlier
4. Pattern to follow in future"
Best Practices
- State the problem clearly - Writing it out often reveals the issue
- List what you've tried - Prevents repeating failed approaches
- Question assumptions - Often the issue is a wrong assumption
- Simplify - Remove code until you find the minimal case
- Take breaks - Fresh eyes see what tired ones miss
- Ask for help early - Don't spend hours on a 5-minute question
- Document the solution - Future you will thank present you
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
johnlindquist/claude
testgen
Generate tests using AI and run test suites. Use for generating unit tests, running coverage reports, and mutation testing.
johnlindquist/claude
article
Generate technical articles and documentation using AI. Use for writing blog posts, documentation, and technical content.
johnlindquist/claude
packx
Bundle code context for AI. ALWAYS use --limit 49k unless user explicitly requests otherwise. Use for creating shareable code bundles and preparing context for LLMs.
johnlindquist/claude
long-agent
Manage long-running agent sessions. Use for tracking progress in extended tasks, maintaining context across long sessions, and managing multi-step workflows.
johnlindquist/claude
db
Database operations for SQLite, PostgreSQL, and MySQL. Use for queries, schema inspection, migrations, and AI-assisted query generation.
johnlindquist/claude
investigate
Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.
Didn't find tool you were looking for?