debug
Diagnosis before prescription: reproduce, hypothesize, isolate, fix root cause, add a regression test; refactor mode maps deps, coupling and blast radius. Triggers: bug, error, fix, broken, not working, crashed, stack trace, exception, refactor, restructure, coupling, dependency map.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- debug
- kernel
- { "kind": "workflow", "version": 1, "confirmation": "none", "side_effects": "none" }
- description
- Diagnosis before prescription: reproduce, hypothesize, isolate, fix root cause, add a regression test; refactor mode maps deps, coupling and blast radius. Triggers: bug, error, fix, broken, not working, crashed, stack trace, exception, refactor, restructure, coupling, dependency map.
- allowed-tools
- Read, Bash, Grep, Glob, Write, Agent
- user-invocable
- true
02 资源文件 1
- 参考文档reference/debug-research.md18.4 KB
03 SKILL.md 正文
<skill id="debug">
<purpose> Debugging is forming and testing a THEORY that explains the bug. Not random changes. Not guessing. Scientific method applied to code. DEFECT (in code) → INFECTION (in state) → FAILURE (visible symptom). The failure you see is NOT where the bug is. Binary search upstream. Systematic methodology beats ad-hoc guessing. The process is the multiplier.
Diagnosis comes before prescription: a surgeon cutting before the X-ray is guessing with a
knife. Two modes, same discipline. bug (default) is the steps below. refactor swaps the
subject from a failure to a structure, and produces a plan instead of a fix.
</purpose>
<prerequisite>Run agentdb recall with the exact error text, subsystem/library, failing
test, and known files/symbols. Recall again when the hypothesis changes or a new failure
appears; that is a new retrieval question. Reference on demand:
skills/debug/reference/debug-research.md.</prerequisite>
<steps>
-
REPRODUCE: get specific before touching code.
- Document: exact input, expected output, actual output (full stack trace), environment, frequency.
- "Sometimes fails" is not a reproduction. Get deterministic.
- Sensitive or high-blast-radius bug: investigate read-only (plan mode) and settle the approach before any edit. <!-- Updated 2026-09-20: sitepoint.com / claudelog.com Claude Code debugging guides -->
- (gate: can reproduce consistently, OR have added targeted logging to wait for next occurrence)
-
HYPOTHESIZE: list 3 causes before pursuing any.
- Read ALL error output first (anchoring bias mitigation).
- Write each hypothesis to AgentDB. Prevents circular re-investigation.
- (gate: 3 candidate hypotheses written; none pursued yet)
-
ISOLATE: binary search, O(log n) not O(n).
-
Code: call chain A→B→C→D→E fails → check midpoint C → recurse into failing half.
-
Time:
git bisectbetween known-good and known-bad commit. ~10 tests for 1000 commits. -
Input: large failing input → split in half → recurse to minimal reproduction case.
-
Instrument at boundaries: log inputs/outputs at each layer boundary.
-
Mock external dependencies to isolate which one causes failure. <!-- Updated 2026-09-19: dev.to flaky-test patterns; claudelog/sfeir debugging guides -->
-
Diff working vs failing state (env, config, input, commit) before theorizing.
-
Flaky test: classify first as timing/race, shared state, unseeded randomness, or environment difference; only then propose a fix.
-
(gate: failure localized to a specific function/commit/input subset)
-
-
ROOT CAUSE: the error line is the FAILURE. The DEFECT is upstream.
- Ask: what assumption was violated? What invariant broke?
- If you can't explain WHY it broke, you haven't found root cause.
- Top causes by frequency: wrong input shape/type · off-by-one · missing null check · race condition · shared-state mutation · wrong comparison operator · variable scope · swallowed error · API contract mismatch · environment difference.
- (gate: can state root cause in one sentence explaining the violated invariant)
-
FIX: root cause, not symptom.
- Fix the DEFECT, not the FAILURE site. (Null check at crash site = symptom fix.)
- Write regression test that fails before fix, passes after.
- Run: original failing case + edge cases + full regression suite.
- Commit fix + test together.
- (gate: regression test green; original failing case passes) </steps>
<refactor_mode> Triggers: refactor, restructure, clean up, coupling, dependency, "what breaks if". Same rule: diagnose, then hand off. Do not start cutting inside this mode.
- MAP: every file/module touching the target. Grep/Glob every reference, or
graphify affected <symbol>when the graph is fresh. Build the import/call map. - TRACE DEPS: per file, who calls it, who depends on it, what breaks if it changes.
- MEASURE COUPLING: cross-module reference counts, circular dependencies, the
per-function CCN from
scripts/complexity.sh. - RISKS: current edge cases, what is tested, what is not, invariants to preserve.
- PLAN: files in change order, tests that must pass before AND after, tier by reversibility x blast radius (file count is only a weak hint). Hand off to /kernel:simplify to execute, which owns the preservation contract and the gate. </refactor_mode>
<diagnosis_output> When the run ends at a diagnosis rather than a fix, emit this and stop:
## Diagnosis: <title>
Mode: bug | refactor · Confidence: high | medium | low
Root cause: <one sentence naming the violated invariant>
Affected: <file - origin> | <file - downstream> ...
Blast radius: N files. Tier 1|2|3.
Hypotheses: 1. <h> -> CONFIRMED | REJECTED (<evidence>) ...
Recommended approach: <what, not how>
Tests required: <fails before> / <passes after>
Next: /kernel:ingest to implement, /kernel:simplify to restructure.
Decide and state the recommendation. Never stop to ask which hypothesis to pursue. </diagnosis_output>
<anti_patterns> Shotgun (random changes until it works) · fix-and-pray (never re-run the original case) · symptom fixing (null check at the crash site) · printf flooding (binary search first, then targeted logging) · blame-the-framework (it's almost never the library) · unscoped "investigate" (scope narrowly or use a subagent so the file reads don't fill context). </anti_patterns>
<when_stuck> Explain the problem in writing · re-read the error message (the answer is there most of the time) · reduce to a minimal reproduction · ask "what changed?" (git log/diff, deps, env) · search the exact error message in quotes · step away, bias accumulates. Re-run the EXACT original failing case before declaring victory; "seems to work" is not evidence. </when_stuck>
<escalation> 30+ min on one hypothesis with no evidence → abandon it. 3+ hypotheses rejected → step back, re-examine assumptions. 2 failed fix attempts → invoke tearitapart; it may be a design problem. Repeated failed corrections in one session → /clear with a minimal reproduction. Bug only in production → add targeted monitoring, document, move on. For 3+ plausible causes, spawn one fresh-context agent per hypothesis (evidence_for / evidence_against / confidence); fresh context catches what a long session anchors past. </escalation>
<telemetry> agentdb emit command "debug" "" '{"mode":"bug|refactor","confidence":"high|medium|low","blast_radius":N,"tier":N}' </telemetry>
<on_complete> agentdb write-end '{"skill":"debug","bug":"<description>","root_cause":"<what_broke>","fix":"<what_fixed>","test":"<regression_test_name>","learned":"<pattern_for_future>"}' </on_complete>
</skill>
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.