systematic-debugging
Systematic debugging and root cause analysis. Strictly forbids speculative code edits and guess-fixing.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- systematic-debugging
- description
- Systematic debugging and root cause analysis. Strictly forbids speculative code edits and guess-fixing.
03 SKILL.md 正文
Systematic Debugging & Root Cause Analysis
Stop guessing. AI agents often jump straight to editing code based on assumptions, creating regressions and compound bugs. Follow this systematic 5-phase protocol for all debugging and bug-fixing tasks.
The 5-Phase Debugging Protocol
Phase 1: Reproduce & Observe
- Do not touch production code yet.
- Reproduce the failure via a test case, minimal script, or terminal command.
- Capture the exact error message, stack trace, and relevant log lines.
- If reproduction isn't possible (e.g., environment-specific), explicitly state the reproduction barrier and analyze existing telemetry/logs.
Phase 2: Trace & Hypothesize
- Trace data flow backwards from the point of failure to the input origin.
- Formulate a single, testable hypothesis: "The error occurs because X receives Y when Z happens."
- Verify the hypothesis by inspecting state (logs, debugger, or code inspection) before changing any logic.
Phase 3: Root Cause Over Symptom Patching
- Fix the root cause, never just patch the symptom.
- If a function crashes on unexpected
null/undefined, determine why it was null instead of just slapping an optional chaining?.or fallback|| {}. - Caller Audit: Use
grep/ codebase search to inspect all callers of any shared function you modify. Fixing only the path mentioned in a bug report leaves sibling callers broken.
Phase 4: Surgical Minimal Fix
- Implement the smallest, cleanest fix that completely resolves the root cause.
- Preserve existing architecture and conventions.
- Do not refactor unrelated code or add unrequested dependencies in the name of a bug fix.
Phase 5: Verification & Regression Prevention
- Re-run the reproduction step from Phase 1 to prove the fix works.
- Run the project test suite and linter to ensure zero regressions.
- When possible, write or update an automated unit/integration test covering the edge case to prevent the bug from ever returning.
04 同仓库更多 Skills
writing-shape
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
writing-beats
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.