From octo
Guides systematic debugging of bugs, test failures, unexpected behavior via 4 phases: root cause investigation, pattern analysis, hypothesis testing, implementation.
npx claudepluginhub nyldn/claude-octopus --plugin octoThis skill uses the workspace's default tool permissions.
**When this skill is invoked, you MUST follow the 4-phase debugging process below. You are PROHIBITED from:**
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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".When debugging a specific module, automatically activate freeze mode to prevent accidental edits outside the investigated area. This is a safety measure that keeps your debugging 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.