设计与 UI
debugging-and-error-recovery
Guide systematic root-cause debugging. Use when tests fail, builds break, runtime behavior is unexpected, logs show errors, or repeated fixes are not resolving the same issue.
HsienW · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add HsienW/ai-agent-engineering-playbook --skill debugging-and-error-recovery技能说明
name: debugging-and-error-recovery description: Guide systematic root-cause debugging. Use when tests fail, builds break, runtime behavior is unexpected, logs show errors, or repeated fixes are not resolving the same issue.
Debugging and Error Recovery
Skill Interface
- Name: debugging-and-error-recovery.
- Description: Guide systematic root-cause debugging when tests fail, builds break, runtime behavior is unexpected, logs show errors, or repeated fixes do not resolve the same issue.
- Parameters: Exact symptom, failing command or workflow, inputs, outputs, logs, timestamps, environment details, recent diffs, and available reproduction or verification commands.
- Instructions: Use this skill before changing code for an unclear failure. Reproduce the issue, identify the failing layer, test one hypothesis at a time, preserve evidence, and re-run the original reproduction after the fix.
Prove the failure before changing code. Keep the investigation narrow until the failure layer is known.
Triage
- Capture the exact symptom, command, input, output, timestamp, and environment.
- Reproduce with the smallest reliable case.
- Identify the failing layer: UI rendering, state management, transport, validation, domain logic, persistence, provider, tool execution, synthesis, or infrastructure.
- Compare expected and actual structured data.
- Form one hypothesis and test it.
- Fix the root cause.
- Re-run the original reproduction and adjacent regression checks.
Stop Rules
Stop local patching and re-evaluate when:
- Two fixes fail to resolve the same symptom.
- A fix for one case breaks another case.
- The failure appears to move between layers.
- Passing requires more special cases or prompt examples.
- Mocks pass but real runtime behavior still fails.
Evidence to Preserve
- Failing test output.
- Minimal input and actual output.
- Relevant logs or traces.
- Diff between previous and current structured data.
- The command used to verify the fix.
Recovery Rules
- Do not delete failing tests to get green output.
- Do not weaken assertions without explaining why the old expectation was wrong.
- Do not ignore caught errors unless the behavior is intentional and tested.
- Do not mask race conditions with fixed sleeps.
- Do not claim a live integration is fixed when only a mock was tested.
Final Check
Report what failed, what changed, what evidence proves the fix, and what remains unverified.