菜单
Guides systematic root-cause debugging through four phases. Use when encountering any bug, test failure, or unexpected behaviour, before proposing fixes.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | debug |
| description | Guides systematic root-cause debugging through four phases. Use when encountering any bug, test failure, or unexpected behaviour, before proposing fixes. |
| license | MIT |
| context | fork |
| agent | general-purpose |
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: Find root cause before attempting fixes. Symptom fixes are failure.
No fixes without root cause investigation first.
If you have not completed Phase 1, do not propose fixes.
Use for any technical issue:
Use this especially when:
Do not skip when:
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 the system has multiple components (CI to build to signing, API to service to database):
Before proposing fixes, add diagnostic instrumentation:
For EACH component boundary:
- Log what data enters the component
- Log what data exits the component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyse evidence to identify failing component
THEN investigate that specific component
Trace data flow
When the error is deep in the call stack, see references/root-cause-tracing.md for the complete backward tracing technique.
Quick version:
Find the pattern before fixing:
Find working examples
Compare against references
Identify differences
Understand dependencies
Apply the scientific method:
Form single hypothesis
Test minimally
Verify before continuing
When you do not know
Fix the root cause, not the symptom:
Create failing test case
Implement single fix
Verify fix
If fix does not 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, step 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. |
A CI build fails at the code signing step. Instead of guessing which secret is missing, add logging at each boundary:
# 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 to workflow passed, workflow to build failed). Fix at the failing boundary, not at the symptom.
**Flaky test with arbitrary timeouts**A test fails intermittently:
Expected: { status: 'completed', amount: 100 }
Received: { status: 'pending', amount: 100 }
Bad approach (Phase 3 violation -- multiple untested fixes):
await sleep(100) -- failsawait sleep(500) -- still failsawait sleep(2000) -- works sometimesCorrect approach (follow Phase 1):
pending -- the update has not completedFix: replace sleep() with condition-based waiting. See references/condition-based-waiting.md.
Symptom: .git directory created inside source code instead of temp directory.
Phase 1 trace:
git init runs in process.cwd() -- empty cwd parameterWorktreeManager.createSessionWorktree(projectDir, sessionId) -- projectDir is empty stringSession.initializeWorkspace() passed empty stringSession.create() used context.tempDir before beforeEach ransetupCoreTest() returns { tempDir: '' } initiallyRoot cause: top-level variable initialisation accessing a value before the test framework sets it.
Fix: made tempDir a getter that throws if accessed before beforeEach. Then added defence-in-depth at all four layers. See references/defense-in-depth.md.
| 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 the issue is truly environmental, timing-dependent, or external:
But: 95% of "no root cause" cases are incomplete investigation.
These techniques are available in references/:
references/root-cause-tracing.md -- Trace bugs backward through call stack to find original triggerreferences/defense-in-depth.md -- Add validation at multiple layers after finding root causereferences/condition-based-waiting.md -- Replace arbitrary timeouts with condition pollingRelated skills:
From debugging sessions:
Guides users through creating effective Claude Code skills with specialized knowledge, workflows, and tool integrations. Use when users want to create a new skill, update an existing skill, extract business logic into reusable packages, or ask about skill structure, frontmatter, or bundled resources.
Extracts text and tables from PDFs, creates new documents, merges/splits files, fills forms, and converts markdown to PDF. Use when working with PDF files, when the user mentions PDFs, document extraction, form filling, OCR, or markdown-to-PDF conversion.
Creates, edits, and analyses PowerPoint presentations with layouts, speaker notes, and design elements. Use when working with .pptx files, creating presentations from topics, modifying slides, or extracting content. Triggers: 'create presentation from topic', 'slide deck from document', 'powerpoint from scratch'.
Audits a codebase for production readiness across six dimensions: API completeness, frontend-backend sync, security, scalability, infrastructure, and dead code/architecture. Use when asked for a launch assessment, production readiness check, pre-deployment audit, or multi-agent patchwork cleanup.
Guides README creation and improvement with audience-matched templates. Use when writing READMEs for open source, personal, internal, or config projects, or when the user mentions documentation, README, or project setup.
Guides Remotion video development in React, including compositions, animations, timing, audio, captions, and rendering. Use when the user works with Remotion, writes <Composition>/<Sequence>/interpolate/spring, edits remotion.config.ts, renders or deploys Lambda videos, or asks about video creation in React.