Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# Debugging and Error Recovery
## Overview
Systematic debugging with structured triage. When something breaks, stop adding features, preserve evidence, and follow a structured process to find and fix the root cause. Guessing wastes time. The triage checklist works for test failures, build errors, runtime bugs, and production incidents.
## When to Use
- Tests fail after a code change
- The build breaks
- Runtime behavior doesn't match expectations
- A bug report arrives
- An error appears in logs or console
- Something worked before and stopped working
## The Stop-the-Line Rule
When anything unexpected happens:
```
1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage checklist
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes
```
**Never push past a failing test or broken build to work on the next feature.** Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-10 wrong.
## The Triage Checklist
Work through these steps in order. Do not skip steps.
### Step 1: Reproduce
…
The line at the top of this page pins the label git:20260215.45942b0, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_scfa65ac2oa3azqs
GET https://markdownregistry.com/api/v1/resolve?ref=lll0k0lad/agent-skills/debugging-and-error-recovery
GET https://markdownregistry.com/api/v1/blob/97588b56aada91bf95b360d4f91d5dd49f527ad390848c0171def0de24ac3f95
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
lll0k0lad/agent-skills · skills/api-and-interface-design/SKILL.md · Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints…
lll0k0lad/agent-skills · skills/browser-testing-with-devtools/SKILL.md · Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console…
lll0k0lad/agent-skills · skills/ci-cd-and-automation/SKILL.md · Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure…
lll0k0lad/agent-skills · skills/code-review-and-quality/SKILL.md · Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you…
lll0k0lad/agent-skills · skills/context-engineering/SKILL.md · Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to…
lll0k0lad/agent-skills · skills/documentation-and-adrs/SKILL.md · Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context…
lll0k0lad/agent-skills · skills/frontend-ui-engineering/SKILL.md · Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing…
lll0k0lad/agent-skills · skills/git-workflow-and-versioning/SKILL.md · Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work…
lll0k0lad/agent-skills · skills/idea-refine/SKILL.md · Refine ideas through structured divergent and convergent thinking. Use "idea-refine" or "ideate" to trigger.
lll0k0lad/agent-skills · skills/incremental-implementation/SKILL.md · Use when implementing any feature or change that touches more than one file. Use when you're about to write a large…
addyosmani/agent-skills · skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke…
shashankswe2020-ux/whoop-mcp · .github/skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-forgecat/platforms/cursor/.cursor/skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-forgecat/platforms/codex/.agents/skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-codex/.agents/skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-forgecat/skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-cursor/.cursor/skills/debugging-and-error-recovery/SKILL.md · Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke…
