القائمة
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. 遇到任何错误、测试失败或意外行为时使用，在提出修复方案之前。 适用于：调试、找 bug、修复问题、测试失败、排查错误、系统性调试、根本原因分析。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when you have a written implementation plan to execute in a separate session with review checkpoints. 有书面实现计划需要批次执行并设置检查点时使用。 适用于：执行已有计划、按计划实现、批次执行任务、分批推进开发。
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup 实现完成、所有测试通过，需要决定如何集成工作时使用。 适用于：完成分支、合并分支、结束开发、提 PR、合并代码、完成功能开发。
Use when completing tasks, implementing major features, or before merging to verify work meets requirements. 完成任务、实现主要功能或合并前验证工作是否满足要求时使用。 适用于：代码审查、code review、审查代码、检查代码质量、提交前审查。
Use when executing implementation plans with independent tasks in the current session. 在当前会话中执行含有独立任务的实现计划时使用。 适用于：执行计划、子代理开发、自动实现、开始实现计划、逐任务执行、两阶段代码审查。
Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions. 开始任何对话时使用 - 建立如何查找和使用技能的规则，在任何回应（包括澄清问题）之前必须调用技能工具。
Use when you have a spec or requirements for a multi-step task, before touching code. 当有规格或需求需要执行多步骤任务时使用，在编写任何代码之前。 适用于：写实现计划、制定开发计划、做规划、拆分任务步骤、编写执行方案。
| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. 遇到任何错误、测试失败或意外行为时使用，在提出修复方案之前。 适用于：调试、找 bug、修复问题、测试失败、排查错误、系统性调试、根本原因分析。 |
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
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
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.
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. |
| 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: