Menu
Debug issues methodically — use when stuck on errors, test failures, or unexpected behavior
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/nyldn/claude-octopus --skill skill-debugThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Decompose large tasks across parallel agents — use for migrations, multi-file refactors, or batch work
Decompose large tasks across parallel agents — use for migrations, multi-file refactors, or batch work
Multi-AI validation, scoring, and review using available external providers (Double Diamond Deliver phase)
Based on SOC occupation classification
| name | skill-debug |
| disable-model-invocation | true |
| aliases | ["debug","systematic-debugging"] |
| description | Debug issues methodically — use when stuck on errors, test failures, or unexpected behavior |
| trigger | EXPLICITLY USE when encountering bugs or failures: - "fix this bug" or "debug Y" or "troubleshoot X" - "why is X failing" or "why isn't X working" or "why doesn't X work" - "why did X not work" or "why didn't X happen" - "X does not work" or "X is broken" or "X is not working" - "investigate Y" or "figure out why Z" - "The X button does not work" or "X preview button does not work" ESPECIALLY use when under time pressure or after multiple failed fix attempts. DO NOT activate for: - "Why do we use X?" (explanation, not debugging) - "Why should I choose X?" (decision support, not debugging) - Known issues with clear solutions - Documentation or architecture questions |
| execution_mode | enforced |
| pre_execution_contract | ["visual_indicators_displayed"] |
| validation_gates | ["orchestrate_sh_executed","debug_output_exists"] |
When this skill is invoked, you MUST follow the 4-phase debugging process below. You are PROHIBITED from:
Systematic debugging finds root causes in 15-30 minutes. Random fixes waste 2-3 hours. Follow the process.
Your first output line MUST be: 🐙 **CLAUDE OCTOPUS ACTIVATED** - Systematic Debugging
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
If you haven't completed Phase 1, you cannot propose fixes.
Use for ANY technical issue:
Use ESPECIALLY when:
┌──────────────────┐
│ Phase 1: ROOT │ ← Understand WHAT and WHY
│ CAUSE │
└────────┬─────────┘
↓
┌──────────────────┐
│ Phase 2: PATTERN │ ← Find working examples
│ ANALYSIS │
└────────┬─────────┘
↓
┌──────────────────┐
│ Phase 3: │ ← Form and test hypothesis
│ HYPOTHESIS │
└────────┬─────────┘
↓
┌──────────────────┐
│ Phase 4: │ ← Fix root cause, not symptom
│ IMPLEMENTATION │
└──────────────────┘
You MUST complete each phase before proceeding.
BEFORE attempting ANY fix:
git diff HEAD~5
git log --oneline -10
When system has multiple components (API → service → database):
# Add diagnostic instrumentation at EACH boundary
echo "=== Layer 1: API endpoint ==="
echo "Input: $INPUT"
echo "=== Layer 2: Service layer ==="
echo "Received: $DATA"
echo "=== Layer 3: Database ==="
echo "Query: $QUERY"
Run once to gather evidence showing WHERE it breaks.
When error is deep in call stack:
| Result | Action |
|---|---|
| Hypothesis confirmed | Proceed to Phase 4 |
| Hypothesis wrong | Form NEW hypothesis, return to Phase 3.1 |
| Still unclear | Gather more evidence, return to Phase 1 |
| Attempts | Action |
|---|---|
| < 3 | Return to Phase 1, re-analyze with new information |
| ≥ 3 | STOP. Show your work. Ask the user. |
Anti-rationalization rules:
Pattern indicating architectural problem:
STOP and question fundamentals:
Discuss with user before attempting more fixes. Do not attempt a 4th fix without explicit user approval.
When debugging involves multiple fix attempts, track a WTF score to detect runaway fix loops. This complements the 3-Strike Rule above with quantitative drift detection.
Track these signals (default weights, override via ~/.claude-octopus/loop-config.conf):
| Event | Score Impact |
|---|---|
| Revert (git revert, undo, roll back a fix) | +15% |
| Touching files unrelated to the bug | +20% |
| A fix that requires changing >3 files | +5% |
| After the 15th fix attempt | +1% per additional fix |
| All remaining issues are Low severity | +10% |
If WTF score exceeds 20% — STOP immediately, even if under the 3-strike limit. Show the score breakdown and ask the user whether to continue.
Also watch for stuck patterns: If the same error message appears 3+ times across fix attempts, or you see A→B→A→B oscillation (fix X breaks Y, fix Y breaks X), announce the cycle and HALT on second detection.
Report the score with each fix attempt:
Fix attempt 2 | Self-regulation: 15% (1 revert, 0 unrelated files)
After 2 failed fix attempts, stop and reconsider the root cause before trying another fix. If the strategy-rotation hook fires, it means you have been repeating a failing approach. Do not continue down the same path — return to Phase 1 and investigate from a different angle.
If you catch yourself thinking:
ALL of these mean: STOP. Return to Phase 1.
| Excuse | Reality |
|---|---|
| "Issue is simple" | Simple issues have root causes too. |
| "Emergency, no time" | Systematic is FASTER than thrashing. |
| "Just try this first" | First fix sets the pattern. Do it right. |
| "I see the problem" | Seeing symptoms ≠ understanding root cause. |
| "One more attempt" | 3+ failures = architectural problem. |
If you suspect the issue is with the Claude Code environment itself (e.g., network errors, context limits, tool failures):
/debug: This native command generates a debug bundle to help troubleshoot platform issues./debug output: Look for "Context limit", "API error", or "Tool execution failed".Inside this explicitly invoked debugging workflow, activate freeze mode for the specific module before editing. This safety measure keeps the investigation focused.
At the start of Phase 1 (Root Cause Investigation), identify the primary module directory being debugged and activate freeze mode:
# Determine the module directory from the error location or user-specified target
# Example: if debugging src/auth/login.ts, freeze to src/auth/
freeze_dir="$(cd "<module-directory>" 2>/dev/null && pwd)"
echo "${freeze_dir}" > "/tmp/octopus-freeze-${CLAUDE_SESSION_ID:-$$}.txt"
This ensures that during investigation (Phases 1-3), you cannot accidentally modify files outside the module under investigation. When you reach Phase 4 (Implementation), the freeze boundary keeps your fix scoped to the right module.
Auto-freeze activates when:
src/auth/, lib/database/)Auto-freeze does NOT activate when:
After debugging completes, remind the user to run /octo:unfreeze if needed, or remove the state file automatically.
When using octopus workflows for debugging:
| Workflow | Debugging Integration |
|---|---|
probe | Research error patterns, similar issues |
grasp | Define the problem scope clearly |
tangle | Implement the fix with TDD |
squeeze | Verify fix doesn't introduce vulnerabilities |
grapple | Debate architectural alternatives after 3+ failures |
For complex bugs, use parallel exploration:
# Phase 1 parallelized
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Investigate auth failure from 4 angles"
# Perspectives:
# Agent 1: Error message analysis
# Agent 2: Recent changes review
# Agent 3: Data flow tracing
# Agent 4: Environment comparison
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
Proposing fix → Root cause investigation completed
Otherwise → Not systematic debugging
Systematic approach: 15-30 minutes to fix. Random fixes approach: 2-3 hours of thrashing.
No shortcuts for debugging.