Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/skill-debug
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Debug issues methodically — use when stuck on errors, test failures, or unexpected behavior
📊 Stats
Stars3,869
Forks362
LanguageShell
LicenseMIT
📦 Ships with octo
</> SKILL.md
skill-debug.SKILL.md
---name: skill-debug
aliases:
- debug
- systematic-debugging
description: "Debug issues methodically — use when stuck on errors, test failures, or unexpected behavior"
trigger: |
AUTOMATICALLY ACTIVATE 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
---# Systematic Debugging
- "I'm pretty sure this fixes it" → Pretty sure is not verified. **Run the test.**
### 5. After 3+ Failed Fixes: Question Architecture
**Pattern indicating architectural problem:**
- Each fix reveals new coupling/problem elsewhere
- Fixes require "massive refactoring"
- Each fix creates new symptoms
**STOP and question fundamentals:**
- Is this pattern fundamentally sound?
- Are we sticking with it through inertia?
- Should we refactor architecture vs. continue fixing symptoms?
**Discuss with user before attempting more fixes. Do not attempt a 4th fix without explicit user approval.**
---
## Self-Regulation Score (Debug Fix Loops)
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.
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.
---
## Red Flags - STOP and Follow Process
If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see"
- "Skip the test, I'll manually verify"
- "It's probably X, let me fix that"
- "I don't fully understand but this might work"
- "One more fix attempt" (when already tried 2+)
**ALL of these mean: STOP. Return to Phase 1.**
---
## Common Rationalizations
| 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. |
If you suspect the issue is with the Claude Code environment itself (e.g., network errors, context limits, tool failures):
- **Run `/debug`**: This native command generates a debug bundle to help troubleshoot platform issues.
- **Check `/debug` output**: Look for "Context limit", "API error", or "Tool execution failed".
## Auto-Freeze on Debug
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.
### How It Works
At the start of Phase 1 (Root Cause Investigation), identify the primary module directory being debugged and activate freeze mode:
```bash
# Determine the module directory from the error location or user-specified target
# Example: if debugging src/auth/login.ts, freeze to src/auth/
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:**
- The bug is localized to a specific directory (e.g., `src/auth/`, `lib/database/`)
- The user specifies a file or module to debug
**Auto-freeze does NOT activate when:**
- The bug spans multiple modules
- The root cause location is unknown at investigation start
- The user explicitly opts out
After debugging completes, remind the user to run `/octo:unfreeze` if needed, or remove the state file automatically.
---
## Integration with Claude Octopus
When using octopus workflows for debugging:
| Workflow | Debugging Integration |
|----------|----------------------|
| `probe` | Research error patterns, similar issues |
