New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Build Failure Recovery

by jsmastery-pro in jsmastery-pro/jsm-agent-skill

Diagnoses which of three failure modes a stalled AI-assisted build is in, then chooses a targeted fix, a hard reset or a rethink instead of more prompting.

MITAuto-check passedAgent Workflows

Install Build Failure Recovery

skills CLI
$ npx skills add jsmastery-pro/jsm-agent-skill --skill recover -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jsmastery-pro/jsm-agent-skill recover --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jsmastery-pro/jsm-agent-skill.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/recover .claude/skills/recover && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
recover
GitHub stars
218
Token cost
~1.8k tokens
SKILL.md length
805 words
Files
1
Skills in repo
5
Repo updated
First seen
Licence
MIT

At a glance

Diagnoses which of three failure modes a stalled AI-assisted build is in, then chooses a targeted fix, a hard reset or a rethink instead of more prompting.

  • Works in 2 steps: Describe What Went Wrong → Identify the Failure Mode
  • A bug fix has failed more than once and the code is getting messier
  • SKILL.md covers Step 1 — Describe What Went…, Step 2 — Identify the Failure…, Step 3A — Targeted Fix and Step 3B — Hard Reset, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The skill argues that endlessly prompting for fixes pollutes the session and makes the code worse, so it separates diagnosis from treatment. In the first step you describe what you expected, what happened instead and how many fix attempts you have made, since the attempt count shows whether this is a fresh problem or a session that has already gone wrong.

It then sorts the problem into one of three modes. A specific thing is broken: isolated, clear error, an early attempt, so a targeted fix. The session has gone wrong: fixes patch fixes and the context is full of failed attempts, so a hard reset rebuilds the feature in a clean context. The foundation is wrong: the code runs but misunderstands a core requirement, library API or architectural pattern, so the approach itself needs rethinking.

When your agent uses it

  • A bug fix has failed more than once and the code is getting messier
  • Deciding between patching, restarting a session or rethinking the approach
  • Code runs but the behavior is fundamentally wrong

Example prompts

  • “My last three fixes made the cart worse; help me work out whether to reset.”
  • “Diagnose this failure before we try another patch: the login redirect loops.”
  • “The generated code runs but uses the wrong API for payments; decide how to recover.”

Workflow steps

2 steps, taken from the step headings in SKILL.md.

  1. Describe What Went Wrong
  2. Identify the Failure Mode

What it can do on your machine

Read from SKILL.md and the folder at commit fd85d6a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Build Failure Recovery loads about 1.8k tokens when it runs. Until then it costs about 53 tokens; SKILL.md has 805 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~53
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jsmastery-pro/jsm-agent-skill at commit fd85d6a, republished under its MIT licence (© jsmastery-pro). 805 words, ~1,819 tokens.

Download SKILL.mdSave it as .claude/skills/recover/SKILL.md (or your agent's skills folder).
name
recover
description
When something goes wrong during a build, diagnose what type of failure it is before deciding how to respond. Targeted fix, hard reset, or full rethink — the right response depends on the right diagnosis.

Not every problem is a bug. Not every bug needs debugging.

When something goes wrong with AI-assisted development, the instinct is to keep prompting — describe the problem, ask for a fix, get another broken version, describe that problem, ask for another fix. The session gets longer. The context gets polluted. The code gets worse.

The problem is not the code. The problem is not knowing what type of failure you are dealing with.

This skill diagnoses the failure first. Then it prescribes the right response. Those are two separate steps and they cannot be swapped.

Step 1 — Describe What Went Wrong

The developer describes the problem. The skill listens before doing anything else.

Ask:

Describe what is wrong. Be specific:
- What did you expect to happen?
- What happened instead?
- How many times have you tried to fix it already?

Read the answer carefully. The number of fix attempts is important — it tells you whether this is a fresh problem or a session that has already gone wrong.

Step 2 — Identify the Failure Mode

Based on the description, determine which of three failure modes this is.

Failure Mode 1 — A specific thing is broken

Signs:

  • The problem is isolated — one component, one function, one route
  • The rest of the project works correctly
  • This is the first or second attempt at fixing it
  • The error message or wrong behaviour is clear and specific

What it means: This is a normal bug. It has a root cause that can be found and fixed precisely.

Response: Targeted fix — go to Step 3A.

Failure Mode 2 — The session has gone wrong

Signs:

  • Multiple fix attempts have made things worse or created new problems
  • The code has become tangled — fixes are patching fixes
  • Context in this session is full of failed attempts
  • It is no longer clear what the original problem was

What it means: The session is polluted. More prompting will not help — it will compound the damage. The feature needs to be rebuilt in a clean context, not patched further.

Response: Hard reset — go to Step 3B.

Failure Mode 3 — The foundation is wrong

Signs:

  • The code runs but produces fundamentally wrong behaviour
  • Claude has been confidently building something that misunderstands a core requirement, library API, or architectural pattern
  • The problem is not a bug in the implementation — the implementation itself is wrong
  • Fixing individual pieces will not help because the approach is incorrect

What it means: This is not a debugging problem. The approach needs to be reconsidered before any code is written. More implementation in the wrong direction makes things harder to untangle.

Response: Rethink — go to Step 3C.

Tell the developer which failure mode this is before proceeding:

This looks like Failure Mode [1/2/3] — [name].

[One sentence explaining why you identified it this way.]

Here is how we handle this:

Step 3A — Targeted Fix

For Failure Mode 1.

Diagnose before touching code

Ask the developer to share:

  • The exact error message or wrong behaviour
  • The specific file or function where it happens
  • What the code is supposed to do versus what it actually does

Read the relevant code. Do not read the entire codebase — only what is directly relevant to the problem.

Show full SKILL.md (321 more words)Show less
Find the root cause

Identify the root cause before suggesting any fix. A root cause is the actual reason the problem exists — not a symptom of it.

State the root cause clearly:

Root cause: [specific explanation of why this is happening]

This is different from the symptom because: [explanation]
Suggest a precise fix

Describe the fix that addresses the root cause. Not a workaround. Not a patch on top of broken code.

Fix: [what needs to change and why]

This will resolve the root cause because: [explanation]

Wait for the developer to confirm before making any changes.

If the fix does not work

If the suggested fix does not resolve the problem — stop. Do not suggest another fix immediately.

Re-examine the root cause diagnosis. If the fix did not work, the root cause was probably wrong. Diagnose again from the beginning before trying again.

If two root cause diagnoses have both been wrong — this may actually be Failure Mode 2 or 3. Re-evaluate.

Step 3B — Hard Reset

For Failure Mode 2.

Acknowledge the situation honestly
This session has gone too far in the wrong direction
to recover by patching. The right move is a clean start.

This is not a failure — it is the correct response
to a polluted context. A fresh session with clear intent
will be faster than continuing here.
Save what is worth keeping

Before the session ends, extract anything valuable from the current state:

  • What was the original feature supposed to do?
  • What parts of the current implementation, if any, are actually correct?
  • What has been learned about what does not work?
  • What should the next session avoid?

Write this as a brief reset note:

## Reset Note — [Feature Name]

### What we were building
[Original feature description]

### What went wrong
[Honest summary of how the session went off track]

### What to avoid next time
[Specific approaches or patterns that did not work]

### Starting point for next session
[Where to begin fresh — what to keep, what to discard]
Instruct the developer
Next steps:

1. Save this reset note somewhere accessible
2. End this session completely
3. Start a fresh session
4. Begin with /remember restore if memory exists
5. Approach [feature name] again with the reset note as context

Do not continue in this session.

Step 3C — Rethink

For Failure Mode 3.

Name the wrong assumption

The foundation being wrong means something was assumed that should not have been. Find it.

The core issue is not a bug — it is a wrong assumption:

Assumed: [what was assumed]
Reality: [what is actually true]

This means the current implementation cannot be fixed
by patching. The approach needs to change.
Propose the correct approach

Based on the correct understanding, describe what the approach should have been:

Correct approach: [description]

Key difference from current approach: [explanation]

What needs to be discarded: [what cannot be salvaged]
What can be kept: [what is still valid]
Do not start rebuilding immediately

A rethink needs the developer to understand and agree before any code changes. Present the analysis and wait for confirmation.

Does this diagnosis match your understanding?

If yes — we can start fresh with the correct approach.
If no — tell me what I am getting wrong.

Only after the developer confirms does any rebuilding begin.

The Principle

The worst thing you can do when something is broken is keep doing the same thing faster.

Diagnose first. Respond correctly. Different failures need different responses — and knowing which failure you are dealing with is more than half the solution.

© jsmastery-pro, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/recover of jsmastery-pro/jsm-agent-skill.

Open the folder on GitHubat commit fd85d6a

Compare with similar skills

Build Failure Recovery next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Build Failure Recovery compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Build Failure Recovery this skilljsmastery-pro/jsm-agent-skill218—~1.8kAutomated safety check: PassMIT
Analyze Trajectoryyologdev/yoyo-evolve1.9k—~3.6kAutomated safety check: PassMIT
Orca Run Replayiflytek/skillhub5.2k4 repos~3kAutomated safety check: PassApache-2.0
LoopX Self Repairloopx-project/loopx6.2k—~2.2kAutomated safety check: PassApache-2.0
Verification Before Completionforyourhealth111-pixel/Vibe-Skills3.6k—~1.1kAutomated safety check: PassApache-2.0
Diagnosing Superpowers Sessionsobra/superpowers297k3 repos~1.7kAutomated safety check: PassMIT

Similar skills

  • Analyze Trajectory

    yologdev/yoyo-evolve

    Diagnoses a recurring failure such as a stuck task, repeated CI error or frequent reverts by sending sub-agents through the logs and returning one root-cause diagnosis.

    1.9k GitHub stars~3.6k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed

  • Orca Run Replay

    iflytek/skillhub

    Answers questions about a past agent run from its recording, using causal graphs and replay, instead of reconstructing events from memory.

    5.2k GitHub starsUsed in 4 repos~3k tokens
    Agent WorkflowsAuto-check passed

  • LoopX Self Repair

    loopx-project/loopx

    Diagnoses surprising LoopX behavior, such as stale recommendations or tiny progress, assigns it to the responsible layer and repairs it at the lowest durable level.

    6.2k GitHub stars~2.2k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Verification Before Completion

    foryourhealth111-pixel/Vibe-Skills

    Completion-evidence route used before claiming work is complete, fixed, passing, committed, or PR-ready.

    3.6k GitHub stars~1.1k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed

  • Diagnosing Superpowers Sessions

    obra/superpowers

    Investigates a session where Superpowers went wrong, reads the transcripts on disk and produces an evidence-cited report, optionally prepared as a bug report for the maintainers.

    297k GitHub starsUsed in 3 repos~1.7k tokens
    Agent WorkflowsAuto-check passed

  • Octocode Code Research

    bgauryy/octocode

    Researches code with evidence: traces callers, imports and cross-repo links, diagnoses failures and reports findings with exact file and line references and a confidence label.

    949 GitHub stars~1.5k tokensUpdated today
    DevelopmentAuto-check passed

More from jsmastery-pro/jsm-agent-skill

  • Architect Before You Build

    jsmastery-pro/jsm-agent-skill

    Runs a short design conversation before coding: aligns on terms, works through the decisions that matter and ends with a plan you confirm.

    218 GitHub stars~1.1k tokensUpdated 3 mo ago
    Auto-check passed

  • Imprint UI Consistency Registry

    jsmastery-pro/jsm-agent-skill

    Run after building a UI component to record its background, border, radius and text classes in ui-registry.md so later components match what came before.

    218 GitHub stars~2.3k tokensUpdated 3 mo ago
    Auto-check passed

  • Session Save and Restore

    jsmastery-pro/jsm-agent-skill

    Saves the essential state of a coding session to memory.md at the end, restores it at the start of the next one, and keeps secrets out of the saved notes.

    218 GitHub stars~1.9k tokensUpdated 3 mo ago
    Auto-check passed

  • Post-Feature Review

    jsmastery-pro/jsm-agent-skill

    Compares a finished feature with its plan, the project's architecture and design rules, and production-readiness checks, then reports issues without fixing them.

    218 GitHub stars~1.3k tokensUpdated 3 mo ago
    Auto-check passed

Categories

Questions about Build Failure Recovery

What does Build Failure Recovery do?

Diagnoses which of three failure modes a stalled AI-assisted build is in, then chooses a targeted fix, a hard reset or a rethink instead of more prompting. The skill argues that endlessly prompting for fixes pollutes the session and makes the code worse, so it separates diagnosis from treatment. In the first step you describe what you expected, what happened instead and how many fix attempts you have made, since the attempt count shows whether this is a fresh problem or a session that has already gone wrong.

When should I use Build Failure Recovery?

Build Failure Recovery fits situations like: A bug fix has failed more than once and the code is getting messier; deciding between patching, restarting a session or rethinking the approach; code runs but the behavior is fundamentally wrong.

How do I install Build Failure Recovery in Claude Code?

Run `npx skills add jsmastery-pro/jsm-agent-skill --skill recover -a claude-code`. Or copy the skill folder (skills/recover in jsmastery-pro/jsm-agent-skill) into .claude/skills/recover in your project. Claude Code loads it when a task matches its description.

How do I install Build Failure Recovery in Codex?

Run `npx skills add jsmastery-pro/jsm-agent-skill --skill recover -a codex`. Or copy the skill folder (skills/recover in jsmastery-pro/jsm-agent-skill) into .agents/skills/recover in your project. Codex loads it when a task matches its description.

Can I use Build Failure Recovery in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jsmastery-pro/jsm-agent-skill --skill recover -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/recover, .gemini/skills/recover, .github/skills/recover and .opencode/skills/recover in your project.

What does Build Failure Recovery need to run?

SKILL.md names no scripts, command-line tools or credentials: Build Failure Recovery is instructions for the agent only.

Does Build Failure Recovery access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Build Failure Recovery safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Build Failure Recovery use?

Build Failure Recovery is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Build Failure Recovery use?

About 1.8k tokens (SKILL.md is roughly 7.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Build Failure Recovery?

Skills that share tags, products or a category with Build Failure Recovery: Analyze Trajectory (yologdev/yoyo-evolve, 1.9k stars), Orca Run Replay (iflytek/skillhub, 5.2k stars), LoopX Self Repair (loopx-project/loopx, 6.2k stars) and Verification Before Completion (foryourhealth111-pixel/Vibe-Skills, 3.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Build Failure Recovery?

jsmastery-pro (a GitHub organization) maintains it in jsmastery-pro/jsm-agent-skill, which has 218 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on July 9, 2026.

Source: jsmastery-pro/jsm-agent-skill on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.