Menu
Systematic 4-phase debugging with root cause investigation. Use when fixing bugs to prevent random fixes.
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/oimiragieo/agent-studio --skill debuggingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Agent frontmatter enhancements — disallowedTools, mcpServers scoping, fork_eligible field
Context management — pre-compact persistence, threshold alignment, microcompact/circuit breaker detection
Hook enhancements — updatedInput for bash safety prefixes, suppressOutput for verbose blocks, denial-based routing feedback
Showing SKILL.md
| name | debugging |
| description | Systematic 4-phase debugging with root cause investigation. Use when fixing bugs to prevent random fixes. |
| version | 1.1.1 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Edit","Bash","Glob","Grep"] |
| best_practices | ["Investigate root cause before any fix","Reproduce the bug reliably first","Compare working vs broken examples","Make one change at a time"] |
| error_handling | strict |
| streaming | supported |
| verified | true |
| lastVerifiedAt | "2026-02-22T00:00:00.000Z" |
| source | builtin |
| trust_score | 100 |
| provenance_sha | c4c30b4297adcffa |
Mode: Cognitive/Prompt-Driven — No standalone utility script; use via agent context.
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
Use for ANY technical issue:
Use this ESPECIALLY when:
Don't skip when:
| Scenario | Use debugging | Use smart-debug |
|---|---|---|
| Simple, locally reproducible bug | Yes | Overkill |
| Root cause area already known |
| Yes |
| Optional |
| Static analysis / code review bug | Yes | No |
| Runtime / production issue | Start here | Preferred |
| Intermittent / hard-to-reproduce | Escalate | Yes |
| Needs hypothesis ranking gate | No | Yes (blocking) |
| Needs instrumentation + log analysis | No | Yes |
| Observability-driven (traces, APM) | No | Yes |
Rule of thumb: Start with debugging for straightforward bugs. Escalate to smart-debug when you need hypothesis ranking, structured instrumentation, or the bug is intermittent/production-only.
See also: .claude/skills/smart-debug/SKILL.md
You MUST complete each phase before proceeding to the next.
BEFORE attempting ANY fix:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
Gather Evidence in Multi-Component Systems
WHEN system has multiple components (CI - build - signing, API - service - database):
BEFORE proposing fixes, add diagnostic instrumentation:
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
Example (multi-layer system):
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
This reveals: Which layer fails (secrets - workflow OK, workflow - build FAIL)
For distributed/microservice systems — prefer OpenTelemetry traces:
# Query traces by component (preferred over manual echo/env logging)
pnpm trace:query --component <service-name> --event <event-name> --since <ISO-8601> --limit 200
# When trace ID is already known
pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200
Fragmented traces (each service has its own root span, trace IDs don't match across boundaries)
= broken context propagation. Fix traceparent/tracestate header forwarding before investigating business logic.
Instrumentation Gate (before hypothesis generation): If runtime behavior remains unclear after static analysis, add targeted log statements at key decision nodes before generating hypotheses. Use session-scoped log files (
.claude/context/tmp/debug-{sessionId}.log) to capture runtime state. Human-in-the-loop: ask the user to reproduce the bug after instrumentation is added, before analyzing results. Only proceed to Phase 2 once runtime evidence is collected.
Trace Data Flow
WHEN error is deep in call stack:
See root-cause-tracing.md in this directory for the complete backward tracing technique.
Quick version:
Find the pattern before fixing:
Find Working Examples
Compare Against References
Identify Differences
Understand Dependencies
Scientific method:
Form Single Hypothesis
Test Minimally
Verify Before Continuing
When You Don't Know
Fix the root cause, not the symptom:
Create Failing Test Case
tdd skill for writing proper failing testsImplement Single Fix
Verify Fix
Cleanup
rg "debug-{sessionId}" --type-add 'src:*.{js,ts,cjs,mjs}' -tsrc .If Fix Doesn't Work
If 3+ Fixes Failed: Question Architecture
Pattern indicating architectural problem:
STOP and question fundamentals:
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
If you catch yourself thinking:
ALL of these mean: STOP. Return to Phase 1.
If 3+ fixes failed: Question the architecture (see Phase 4.5)
Watch for these redirections:
When you see these: STOP. Return to Phase 1.
| Excuse | Reality |
|---|---|
| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" | Seeing symptoms does not equal understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | 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 |
If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
But: 95% of "no root cause" cases are incomplete investigation.
These techniques are part of systematic debugging and available in this directory:
root-cause-tracing.md - Trace bugs backward through call stack to find original triggerdefense-in-depth.md - Add validation at multiple layers after finding root causecondition-based-waiting.md - Replace arbitrary timeouts with condition polling.claude/tools/analysis/find-polluter/find-polluter.sh (or find-polluter.ps1 on Windows) from the project root to isolate which test pollutes the suite.Related skills:
From debugging sessions:
For distributed systems, OpenTelemetry traces replace manual echo/env evidence gathering. A trace shows the complete request journey across service boundaries via span IDs and trace IDs (W3C Trace Context standard: traceparent/tracestate headers).
Evidence hierarchy for distributed failures (prefer in order):
1. Distributed traces (OpenTelemetry spans, correlated trace IDs)
2. Structured logs with correlation IDs
3. Metrics with timestamps
4. Manual instrumentation (Phase 1 Step 4 bash examples)
Common symptom — fragmented traces: Each service shows its own root span, trace IDs don't match across boundaries. This means context propagation is broken — fix header forwarding before investigating business logic.
LLM-based debugging agents (2025 pattern) augment Phase 1 by reading production traces and correlating with codebase context to suggest minimal reproduction cases.
Use AI assistance for:
Do NOT skip Phase 1 when using AI assistance. AI suggestions are hypotheses — apply Phase 3 (hypothesis testing) before implementing any AI-suggested fix. AI cannot replace systematic investigation; it accelerates evidence gathering.
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| "Quick fix for now, investigate later" | The quick fix becomes permanent; the root cause resurfaces as a different symptom | Always complete Phase 1 before touching production code |
| Making multiple changes at once | Can't determine which change fixed or broke the system; creates regressions | One change per hypothesis test; verify before the next change |
| Proposing AI-suggested fixes without testing | AI suggestions are hypotheses, not facts; applying them blindly skips Phase 3 | Treat AI suggestions as hypotheses to test, not answers to implement |
| Attempting a 4th fix after 3 failures | N+1 fix attempts on a broken approach compound the problem | After 3 failed fixes, escalate to architecture review |
| Skipping the failing test before the fix | You can't verify the fix worked, and regressions are invisible | Create the failing test first; it proves root cause and verifies fix |
Before starting:
Read .claude/context/memory/learnings.md
After completing:
.claude/context/memory/learnings.md.claude/context/memory/issues.md.claude/context/memory/decisions.mdASSUME INTERRUPTION: If it's not in memory, it didn't happen.