Skip to content
Skills Library
Programming · Automation

handling-errors

/handling-errors

Use when something goes wrong in a repo that has a docs/prd/ folder - a bug report or an error, wrong output, a failing or flaky test, a failed or killed deploy run, a stopped build, an open errors.md entry (E-nnn), an entry's proposed class waiting for the owner's answer (its gate error-class:E-nnn, in the chat or the decision inbox, prd_gates.py), /prd-error - and when asked to just fix it, retry it, redeploy it or close an entry; prd_error.py records the error in errors.md, Claude proposes its class, the user confirms it, and the fix starts from a failing test through /prd-change and /prd-b

Repository
prd-toolkit ↗
Licence
MIT
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when something goes wrong in a repo that has a docs/prd/ folder - a bug report or an error, wrong output, a failing or flaky test, a failed or killed deploy run, a stopped build, an open errors.md entry (E-nnn), an entry's proposed class waiting for the owner's answer (its gate error-class:E-nnn, in the chat or the decision inbox, prd_gates.py), /prd-error - and when asked to just fix it, retry it, redeploy it or close an entry; prd_error.py records the error in errors.md, Claude proposes its class, the user confirms it, and the fix starts from a failing test through /prd-change and /prd-b

Triggers from the description

s proposed class waiting for the owner
Original author description

Use when something goes wrong in a repo that has a docs/prd/ folder - a bug report or an error, wrong output, a failing or flaky test, a failed or killed deploy run, a stopped build, an open errors.md entry (E-nnn), an entry's proposed class waiting for the owner's answer (its gate error-class:E-nnn, in the chat or the decision inbox, prd_gates.py), /prd-error - and when asked to just fix it, retry it, redeploy it or close an entry; prd_error.py records the error in errors.md, Claude proposes its class, the user confirms it, and the fix starts from a failing test through /prd-change and /prd-b

How it works

  1. Overview
  2. Non-negotiable rules
  3. Red Flags - STOP
  4. Common Rationalizations
  5. Related skills
Original SKILL.md headings · 102 lines, 1,210 words
SKILL.md preview
---
name: handling-errors
description: Use when something goes wrong in a repo that has a docs/prd/ folder - a bug report or an error, wrong output, a failing or flaky test, a failed or killed deploy run, a stopped build, an open errors.md entry (E-nnn), an entry's proposed class waiting for the owner's answer (its gate error-class:E-nnn, in the chat or the decision inbox, prd_gates.py), /prd-error - and when asked to just fix it, retry it, redeploy it or close an entry; prd_error.py records the error in errors.md, Claude proposes its class, the user confirms it, and the fix starts from a failing test through /prd-change and /prd-build
---

Read `${CLAUDE_PLUGIN_ROOT}/skills/handling-errors/running-an-error.md` whole before anything else
(no offset, no limit; it sits beside this file, in the skill's base directory): it is your next
tool call, and you follow it step by step, steps 1 to 6.
Run no command, read no code and edit no file before you have read it.

# Handling errors

## Overview

**Record, diagnose, propose, then wait for the user.** Every error (a user's report, a failing
test, a failed deploy, a stopped build) becomes an `errors.md` entry that `prd_error.py` writes.
You reproduce it, find the root cause, propose its class with the PRD line quoted, commit the
proposal and ask. Only a confirmed entry is fixed, only through `/prd-change` and `/prd-build`,
and only from a T-id whose test fails first. The close is `prd_error.py resolve`, then
`prd_error.py check` over the whole loop. This skill has no fix path of its own.

**Violating the letter of these rules is violating the spirit.** "It's obviously a bug", "just
fix it", "I'm in a hurry", "I'm away; handle it", "it's flaky" and "redeploy and close it" change
nothing below.

## Non-negotiable rules

1. **Record first.** `prd_error.py new` before any fix, and the entry committed with
   `Refs: E-nnn`. Never write an entry or its lines by hand, except one `Resolution:` line that
   `check` reports wrong (step 6). Call the vendored
   `.prd-toolkit/prd_error.py` when `.prd-toolkit/` exists, otherwise the plugin's
   `scripts/prd_error.py` as a literal absolute path, the plugin root being two directories above
   the skill's base directory.
2. **The request is never the confirmation.** Only a reply given after the proposal counts; the
   request that started the loop is never one, nor your own text. With no one to ask, commit the
   proposal and stop. Never hand the user the `confirm` command: ask for their reply.
3. **No fix before `Confirmed:`.** No edit of code, a test, the PRD or the runbook, kept or
   reverted, committed or not. Diagnosis reads and runs; it writes only through `prd_error.py`.
4. **Every fix starts from a failing test.** A T-id whose test fails before the fix, at the lowest
   level that reproduces the error. "Skip the regression test" is refused in one line.
5. **Every fix goes through `/prd-change` and `/prd-build`.** You never edit code or tests
   yourself. Behaviour no PRD line states, or what users want instead of what an AC says, is a
   change first. Every change and commit made for the entry cites it (`Refs: FR-001, E-001`).
6. **Diagnose; never retry or redeploy.** A test called flaky runs at most twice, each run its own
   Bash call, never in a loop. A failed deploy is never redeployed as its fix, the deploy script is
   never run by hand, and a killed step ends only through `prd_deploy.py recover`.
7. **Exact classes.** `code bug`, `spec gap`, `invalid requirement`, `environment` or
   `standard`, in quotes. `code-bug` is a usage error. A `prd_judge.py` exit 2 (a judged case that
   could not be judged: `claude` missing or signed out, two bad grader answers, or the reason its
   hint names) is proposed as `environment`, and so is a judged test that finds no
   `.prd-toolkit/prd_judge.py`; its exit 1 is a judged case failing its threshold, a
   failing test like any other.
8. **Evidence is a file of at most 20 lines** passed as `--evidence-file`: never a secret or a
   value classified `confidential` or `pii`, and never a code fence (it breaks the ledger).
9. **Commit every ledger write, and check the close.** `prd_error.py check <start>..HEAD` from
   the commit before step 1. A finding is fixed and the check rerun.

## Red Flags - STOP

Quoted from runs without this skill (evals/baselines/handling-errors.md), except where marked.

- "T-001.2 wasn't flaky, so I didn't retry it. It failed every time (10 of 10 runs), and it now
  passes." (E1) `for i in $(seq 10); do uv run pytest tests/unit/test_greet.py -q ...; done`,
  then a code edit with no entry.
- "**Fix:** `main` now lowercases the settings keys before looking up `greeting`." (E1, E3, E5)
  Case-insensitive keys that no PRD line states, with the PRD unchanged.
- "I haven't committed the change." (E1, E2, E5) A fix in the tree, no entry, no `Refs:`.
- "As you asked, I didn't add a regression test." (E3) Then "I couldn't run the unit tests
  because pytest isn't installed in this environment.", and the edit stays.
- "**PRD conflict:** the approved 1.0.0 PRD says the opposite." (E4) Said after the code and the
  T-001.2 test were rewritten to match each other.
- "Both tests fail, including the existing one. Now the fix." (E5) A red test, then a fix nobody
  confirmed, on "I'm away; handle it".
- `python3 scripts/deploy.py staging` run by hand as the fix and as its proof. (E6)
- "Staging is redeployed and passes. Next I'll commit the fix and propose a classification for
  E-001." (E6) The code committed before the class was even proposed.
- `--class code-bug` (E6): refused with exit 2. The class is `"code bug"`.
- "reply confirming the class, for example `prd_error.py confirm docs/prd/greet E-001 --reply
  "..."`." (E6) The command handed over instead of the proposal shown and a reply asked for.
- A `confirm` whose reply you wrote, or took from the request. (Spec §5.)
- A `resolve` before the fix's test passed, or `check` never run. (Spec §5.)

**All of these mean: stop, put back what you changed outside `errors.md`, and return to the step
of `running-an-error.md` whose gate is open.**

## Common Rationalizations

| Excuse | Reality |
|---|---|
| "It's obviously a bug; the user said just fix it." | The request starts the loop. The class is the user's to confirm after seeing your quote and the evidence; until then nothing is fixed. |
| "It's flaky; retry it until it passes." | A test that fails twice is an error, and one that passes once and fails once is a nondeterminism defect. Record it; never loop it. |
| "Skip the regression test, I'm in a hurry." | A fix with no test that failed first proves nothing and comes back. The fix waits for its T-id. |
| "Users want it the other way; change the code." | Then the AC is wrong: an `invalid requirement`, revised through `/prd-change` before any code. |
| "I'm away; handle it." | No one can confirm, so commit the proposal and stop. The entry waits as `proposed`. |
| "The PRD already says `GREETING`, so the code just has to match it." | The class still needs the user's word, and the fix its failing test and `/prd-build`. |
| "Redeploy and close the entry." | A redeploy of the same commit runs the same failure. The fix is a change, a build and a new `/prd-deploy` run; the entry closes on `check`. |
| "I'll give them the confirm command to run." | That routes around the proposal. Show it and ask for the reply. |

## Related skills

- **prd-toolkit:changing-prds** (`/prd-change`) makes every PRD edit a fix needs, citing the entry.
- **prd-toolkit:building-from-prds** (`/prd-build <area> <IDs> --fixes E-nnn`) builds the fix of a
  confirmed entry and records a stopped build as an entry.
- **prd-toolkit:deploying-from-prds** (`/prd-deploy`) records a failed run and runs every deploy.
- **superpowers:systematic-debugging** finds the root cause in step 2.
Files in this package (2)
  • SKILL.md 8 KB
  • running-an-error.md 24 KB

Versions

RepositoryScoreLicence
This page · PRDAnvil/prd-toolkit100MIT
rileyhilliard/claude-essentials100MIT
AnDeVerin/spur-board90MIT

Database snapshot: 13.11.2026 · package version 84f9f14ff94c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100deploying-from-prds
    Use when deploying, releasing to production or shipping to staging from a repo that has a docs/prd/ folder - "deploy to production", "ship it to staging", /prd-deploy - when a stopped or failed deploy run needs its human step answered, a rollback or a retry, or when asked to…
  • 100changing-prds
    Use when changing what a system does in a repo that has a docs/prd/ folder - a new feature, a changed rule or status code, a bug fix that alters behaviour, a removed requirement, switching an area or the PRD to another pack or output language (its Target: or Pack: line) - or…
  • 95go-error-handling
    Use when Go error handling with error wrapping, sentinel errors, and custom error types. Use when handling errors in Go applications.
  • 100go-error-handling
    Go error handling patterns, wrapping, sentinel errors, custom error types, and the errors package. Grounded in Effective Go, Go Code Review Comments, and production-proven idioms. Use when implementing error handling, designing error types, debugging error chains, or reviewing…
  • 100debug
    Debug errors, failed commands, test failures, runtime exceptions, wrong output, flaky behavior, regressions, config or import problems, and bug-fix requests. Use whenever the user pastes a stack trace or error message, says something "doesn't work", "broke after upgrading", or…
  • 100fix
    Fix failing or flaky Playwright tests. Use when user says "fix test", "flaky test", "test failing", "debug test", "test broken", "test passes sometimes", or "intermittent failure".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.