debugging-and-error-recovery
Use when diagnosing bugs, failing checks, unexpected behavior, performance regressions, or repeated unsuccessful fixes.
- License 许可
- MIT
- 最近更新
- 2026-08-20
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- debugging-and-error-recovery
- description
- Use when diagnosing bugs, failing checks, unexpected behavior, performance regressions, or repeated unsuccessful fixes.
02 资源文件 1
- 脚本find-polluter.sh1.5 KB
03 SKILL.md 正文
Debugging and Error Recovery
<HARD-GATE> Root cause over local patch. Reproduce before changing code. Test one hypothesis at a time, fix the invariant that allowed the failure class, and rerun the original scenario before claiming success. </HARD-GATE>
Use this for reported bugs, test/build/runtime failures, unknown regressions, and deep failures whose visible symptom is far from its cause. If the cause is already known, implement the smallest verified fix instead.
Diagnose Loop
- Gather — read the full error, logs, recent changes, and environment. No fix proposal until the symptom fits in one sentence.
- Reproduce — run the failure or state why reproduction is blocked. Reduce it to the smallest failing case.
- Localize — identify the suspect boundary: input, validation, domain logic, persistence, integration, or environment.
- Hypothesize — name one or two candidate causes and the observation that would falsify each.
- Instrument — add the minimum probe, structured boundary log, or failing test that distinguishes the candidates. One hypothesis per probe.
- Confirm or revise — run the probe. Evidence selects the next step; plausibility does not.
- Fix upstream — repair the upstream cause or invariant with the smallest change, not the symptom layer.
- Guard — add a regression test that would have caught the original symptom when feasible.
- Verify — rerun the original reproduction, regression test, and relevant type/lint checks.
Trace Deep Failures Backward
Trace backward from the symptom:
failure <- received input <- caller output <- earlier boundary <- origin of invalid state
At each boundary, record structured input/output evidence and ask: what called this, where did its data come from, and what changed? Log stable identifiers and relevant fields; redact secrets. Do not add broad body logging or ten probes at once.
If an unknown test creates unwanted files or state, use the bundled {baseDir}/find-polluter.sh <path-to-check> <test-pattern> to identify the first polluting test.
Useful clues:
| Symptom | First suspects |
|---|---|
| Dev/prod mismatch | config, data, dependency, race |
| Only one user | identity, permissions, stored data |
| Intermittent failure | timing, ordering, cache, race |
| Recently regressed | recent change, deploy, schema, dependency |
Retry and Escalation
- If an operation fails, reread current state; retry once only if failure may be transient, then use a fallback approach.
- After two unsuccessful fixes, run a map-vs-territory check: reread the request, reproduction, and eliminated hypotheses.
- After three failed fixes, stop and escalate the disputed assumption or architecture. Do not stack another patch.
Evidence Required
Record the reproduction, tested and eliminated hypotheses, confirmed root cause, changed invariant, regression guard, and verification commands. If the bug is non-reproducible or a guard is infeasible, report that limitation explicitly.
04 同仓库更多 Skills
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization. Includes complete pressure testing methodology.
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
typescript-coding-standards
Use when writing, refactoring, or reviewing TypeScript code that needs strong domain modeling, typed errors, schema parsing, safe adapters, test seams, or maintainable module boundaries.
test-driven-development
Use when implementing a feature, bugfix, or behavior-changing refactor — require a failing behavior test before production code, then make the smallest change that passes.
source-driven-development
Use when unfamiliar libraries, dependency internals, external APIs, framework behavior, migrations, or current ecosystem guidance require official documentation, version-matched source, read the tests, and cited evidence.
security-and-hardening
Use when auditing security, implementing authentication or authorization, handling secrets, or validating data across external trust boundaries.