メニュー
A disciplined method for debugging and recovering from failures. Use when something breaks, behaves unexpectedly, a test fails, an error appears, or a bug is intermittent — instead of guessing at fixes or stacking random edits.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | fault-recovery |
| description | A disciplined method for debugging and recovering from failures. Use when something breaks, behaves unexpectedly, a test fails, an error appears, or a bug is intermittent — instead of guessing at fixes or stacking random edits. |
Debug by narrowing, not by guessing. Random edits hide bugs more often than they fix them — and leave you unsure which change mattered. Reproduce the failure reliably, read what the system actually said, isolate the smallest trigger, test one hypothesis at a time, fix the cause, and lock it with a regression test.
This skill is for methodical diagnosis in dev, CI, staging, or post-mitigation production investigation. When users are actively impacted and you need to stop the bleeding first, pair with [[incident-response]] — mitigate before deep root-cause work. For preventing failures at boundaries, see [[resilience]]. For telemetry during diagnosis, see [[observability]].
Skip the full process for a typo with an obvious one-line fix — but still confirm with a test or reproduction if the surface area isn't trivial.
Not this skill alone: active production outage with no mitigation → [[incident-response]] first.
Work in order. Don't edit code until reproduction and the error are understood.
Write a failure record — even three lines — so you don't lose facts while guessing:
Expected: checkout total includes tax for EU addresses
Actual: tax line shows €0.00
First seen: after commit abc123 / in CI job X / only on Safari
Repro rate: always / ~30% / only under load
Error text: (paste or link)
If you can't fill expected vs actual, clarify with the reporter ([[spec-first]]) before debugging.
A bug you can't trigger on demand, you can't prove you fixed.
Make reproduction deterministic:
If intermittent:
--repeat, loop script) to estimate frequencyNo repro after reasonable effort → gather more telemetry ([[observability]]), add logging at boundaries, or pair with the reporter. Don't "fix" what you can't see fail.
The message, stack trace, and logs usually name the neighborhood. Read them before theorizing.
Stack traces
Logs
Tests
pytest path::test, npm test -- -t nameGeneric errors ("Internal Server Error", "Something went wrong") still point somewhere — trace from the handler to where the real exception was swallowed ([[resilience]] red flag).
Shrink the problem space until the failure is small and local.
Git bisect — regression after a range of commits:
git bisect start
git bisect bad # current broken
git bisect good <sha> # known good
# test each step; git bisect good/bad until found
git bisect reset
Code bisect — disable, stub, or bypass halves:
Input minimization — shrink to smallest failing case:
Scope by layer
| Symptom layer | Narrow to |
|---|---|
| UI wrong | DOM/state → network response → server logic → data |
| API wrong | Handler → service → DB query → external dependency |
| Test only in CI | Env diff, parallelism, timing, file order |
| Production only | Config, scale, data shape, deploy artifact |
Document what you ruled out — "not the database" is progress.
A hypothesis is a testable statement that explains all observed evidence:
Bad: "Something's wrong with tax"
Good: "Tax is zero because regionCode is null when EU address uses legacy ISO field"
One hypothesis at a time. If you have two equally likely theories, pick the one you can disprove fastest (cheapest experiment).
Confirm assumptions against source ([[source-first]]) — API signature, default value, query result — not memory of how it "should" work.
Change one thing, observe, record result. Repeat.
| Do | Don't |
|---|---|
| Add one log line at suspect boundary | Refactor while "debugging" |
| Toggle one flag | Change timeout + retry + query together |
| Patch one branch | "Cleanup" unrelated code in same commit |
| Revert one commit to confirm | Stack five speculative fixes |
Keep a debug log for non-obvious sessions:
H1: null region → added log in TaxService → regionCode null on EU path → confirmed
H2: legacy field not mapped → fixed mapper → test green
If a change doesn't help, revert it before the next experiment. Debug commits should not accumulate noise.
Prove the hypothesis:
| Symptom fix (avoid) | Cause fix (prefer) |
|---|---|
catch (e) {} | Why did the exception throw? |
| Retry until pass | Why did the first attempt fail? |
if (x == null) return 0 | Why is x null on a valid path? |
| Hide error in UI | Why did the API return 500? |
@ts-ignore | Fix the type or contract |
Symptom fixes ship silence — the bug persists or corrupts data elsewhere. If a workaround is required temporarily (production hotfix), track a follow-up to fix root cause ([[incident-response]]).
Before closing the bug ([[test-first]]):
Name the test after the behavior: applies_eu_tax_when_legacy_region_field_set.
For flaky bugs, the test may need deterministic timing or explicit ordering — document why.
After one focused hour (or two failed hypotheses with no new data), check common non-code causes:
Environment & versions
.envData
Concurrency & timing
pytest -n0 to compareAssumptions
Get a second pair of eyes with the failure record and debug log — not "it doesn't work."
Time-box — if still stuck, escalate: more telemetry, pair debug, or scope reduction.
Failing unit/integration test
git diff recent changes if regression.CI-only failure
Flaky test
Browser / UI bug ([[browser-checks]])
Wrong output, no exception
Production bug (service stable)
"Worked yesterday" regression
git bisect or scan deploy changelog.console.log / print spam committed as the "fix"Meta-skill that routes a task to the right engineering skill. Load this at the start of a session or when unsure which skill applies — it maps intent to the process that should govern the work.
Catches breaking changes between services before they ship, by testing the contract each consumer actually depends on instead of spinning up the whole system. Use when services deploy independently, when a provider API change could break a consumer, or when end-to-end integration tests are too slow and flaky to guard every service boundary.
Proves whether a change actually moves the metric, with a valid A/B test instead of a guess — a hypothesis, a primary metric, a pre-computed sample size, guardrail metrics, and an honest readout. Use when shipping a change meant to improve a number (conversion, retention, performance), running an A/B or holdout, or deciding whether a feature "worked."
Decouples deploy from release using feature flags — ship code dark, roll out gradually, kill instantly, and remove the flag once it's done. Use when releasing risky or large changes, rolling out by percentage/cohort, delivering A/B variants, or when stale flags are accumulating as debt.
Finds security risks at design time — before code exists — by mapping the system, enumerating how it could be attacked, and deciding what to do about each threat. Use when designing a feature that touches auth, data, money, or external input, when changing a trust boundary, or when a security-sensitive change needs a structured risk pass rather than a code-level review.
Designs durable, curated memory that an agent carries across sessions — what to persist, how to scope and retrieve it, and how to stop it from drifting or poisoning later runs. Use when an agent needs to remember decisions, preferences, or project facts beyond one context window, or when stale/over-generalized memory is corrupting its behavior.