# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-hsienw-ai-agent-engineering-playbook-debugging-and-error-recovery`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HsienW](https://agentstack.voostack.com/s/hsienw)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HsienW](https://github.com/HsienW)
- **Source:** https://github.com/HsienW/ai-agent-engineering-playbook/tree/master/skills-delivery-practices/debugging-and-error-recovery

## Install

```sh
agentstack add skill-hsienw-ai-agent-engineering-playbook-debugging-and-error-recovery
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

1. Capture the exact symptom, command, input, output, timestamp, and environment.
2. Reproduce with the smallest reliable case.
3. Identify the failing layer: UI rendering, state management, transport,
   validation, domain logic, persistence, provider, tool execution, synthesis,
   or infrastructure.
4. Compare expected and actual structured data.
5. Form one hypothesis and test it.
6. Fix the root cause.
7. 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HsienW](https://github.com/HsienW)
- **Source:** [HsienW/ai-agent-engineering-playbook](https://github.com/HsienW/ai-agent-engineering-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hsienw-ai-agent-engineering-playbook-debugging-and-error-recovery
- Seller: https://agentstack.voostack.com/s/hsienw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.