메뉴
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes |
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.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Use for ANY technical issue:
Use this ESPECIALLY when:
Don't skip when:
You MUST complete each phase before proceeding to the next.
BEFORE attempting ANY fix:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
bd ready --explain shows dependency reasoningbd memories <symptom-keywords> (prior root-cause/lesson memories) and bd list --label <topic> --status all (+ bd search "<symptom>" --status all for decision/design knowledge-beads; error strings are body terms: add --desc-contains "<error-string>"; >10 hits: narrow the query, never triage truncated titles). Then read — hits are pointers, not knowledge: bd show <ids> every plausibly-matching prior decision/design, and bd recall <key> every plausibly-matching memory (bd memories prints truncated previews) — full bodies, before investigating further. 0 relevant does not mean none exist — re-angle the query once before emitting KB check: none. Emit KB check: N hits, M read + a one-line disposition each. If a prior root cause or decision already covers this, use it — don't re-debug something already understood.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 ✓, workflow → build ✗)
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
beads-superpowers:test-driven-development skill for writing proper failing testsImplement Single Fix
Verify Fix
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.
After the work is settled, present the Capture gate — mandatory every time; Skip is the default (most work leaves nothing worth keeping):
{
"questions": [{
"question": "Worth keeping anything from this?",
"header": "Capture",
"options": [
{"label": "Skip", "description": "Nothing here outlasts the work itself (usually the case)"},
{"label": "Record the decision", "description": "Pick this if the choice is hard to undo, non-obvious in hindsight, and had real trade-offs — so future-you knows why"},
{"label": "Remember the lesson", "description": "A specific, evidence-backed lesson worth reusing in later sessions"},
{"label": "Both", "description": "A lasting decision and a lesson worth reusing"}
],
"multiSelect": false
}]
}
Route on the answer. Record the decision / Both → this writes an ADR, so first confirm it clears the bar (hard-to-reverse AND surprising-without-context AND genuine trade-off); if it doesn't, say so and capture it as a memory instead (the lighter record) — unless the user confirms they want the full ADR. Write the ADR (docs/decisions/ADR-NNNN-<kebab>.md, sections Context/Decision/Rationale/Consequences, update docs/decisions/INDEX.md), then file a type=decision knowledge-bead so the decision stays retrievable: printf '%s' "<distilled 0.5-2.5KB decision summary — context, decision, consequences>" | bd create "<one-line summary>" -t decision -l kb,adr-process,<topic> --defer 2099-01-01 --metadata "$(jq -nc --arg d "<ADR-path>" '{doc:$d}')" --body-file - --silent (run the secret/PII scan on the summary first — flag for removal, never write a secret into a bead). Remember the lesson / Both → bd remember "<kind>: <durable, evidence-backed insight>". Skip → nothing.
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 ≠ understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
| "Quick patch / retry-timeout wrapper is fine" | A fix that papers over the defect, weakens a security control, or accepts material risk is a symptom fix — forbidden (Production-Grade Doctrine). |
| 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 pollingRelated skills:
From debugging sessions:
Invoked by: Any bug, test failure, or unexpected behaviour. Interrupt skill — fires regardless of workflow position.
Called by: subagent-driven-development — on integration test failures after batch merge.
Pairs with:
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when a design, plan, or decision needs adversarial scrutiny before proceeding. Interrogates every branch of the decision tree, providing recommended answers and forcing explicit agreement or pushback. Triggers on "grill me", "stress test this", "poke holes", "challenge this design", or when brainstorming/writing-plans suggests review.
Use when you have a spec or requirements for a multi-step task, before touching code
Use when checking if beads-superpowers is outdated, before a plugin release, or when auditing for missing capabilities — covers upstream drift, test execution, documentation, plugin health, and content integrity
Use when implementation on a branch is complete and it is about to be merged or PR'd — or when finishing-a-development-branch reaches its docs-audit gate — and after code changes are committed, to ensure all project documentation accurately reflects shipped code. Covers README, ARCHITECTURE, CONTRIBUTING, CHANGELOG, CLAUDE.md, TODOS, and VERSION files. Triggers on "update docs", "sync documentation", "post-ship docs", "document release", "documentation audit".
Use when beads/Dolt database initialization fails, when bd commands return errors about missing databases, when setting up beads in a new project, or when recovering from diverged Dolt history. Handles fresh init, bootstrap from remote, and recovery workflows.