find-cause
The craft of finding a cause: reproduce, isolate, read, state the cause with evidence, fix the cause, run again. Use when a check fails, a test is red, a result is unexpected or a bug is reported, and the cause is not clear after one read.
- License 许可
- MIT
- 所属仓库
- lamtran8401/nook
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- find-cause
- description
- The craft of finding a cause: reproduce, isolate, read, state the cause with evidence, fix the cause, run again. Use when a check fails, a test is red, a result is unexpected or a bug is reported, and the cause is not clear after one read.
- user-invocable
- false
03 SKILL.md 正文
Goal: a fix that removes the cause, not one that hides the symptom. A guessed fix passes today and fails next week, and it costs a failed review. For a plain typo, fix it and move on.
Order
- Reproduce. Run the failing command. Copy the first error and its location. When it does not fail again, you have no bug yet: find what differs (order, time, state, environment).
- Isolate. Run the smallest test or command that still fails. Remove what does not matter: other tests, other files, other input.
- Read. The code at the error and one level up. What changed:
git diff,git log -5. The cause is often in the last change. - State the cause in one sentence, with the evidence. When you cannot, make the value visible: one print or one test that shows it, run again, then remove the print.
- Fix the cause. Do not widen a test, skip a test or add a retry.
- Run the failing command again, then the checks of the area.
Kinds of failure
a test fails after your change the change is the first suspect: read the diff, then the test
a test fails and you did not touch it something it depends on changed: another test, a shared helper, the order, the clock
a build fails read the first error only: the later ones often follow from it
a type error check the generated types: a contract change can need codegen
works alone, fails in the suite shared state or test order: find what the first test leaves behind
fails only in CI or only here the environment: versions, env variables, the lockfile, the time zone
When you are stuck
After three tries with no progress, stop.
A builder runs nook task fail <id> <T> --reason "<the command, the first error, what you ruled out, your best guess>", so the lead continues without you.
The lead reports the same four things to the owner.
Cause: `listShipments` builds the query before it reads `status`, so the filter never applies. Evidence: `list.ts:42` reads `params` at line 51.
Fix: read `status` first. The test "filters by status" fails without the fix and passes with it.
Checks: bff lint and test pass.
Gotchas
- Change one thing at a time. A cause that you cannot trigger again is a guess.
- A pass after a retry is not a fix. Find why the first run failed.
- Read the first error, not the last.
- A test that depends on the clock, the network or the order of tests is the bug. Fix the test or the code, not the retry.
- A fix outside the folder of your slice is a question for the lead, not a change you make.
- Experiments go in
$TMPDIR, never under~/.claudeor in an area you do not own.
04 同仓库更多 Skills
yolo
Run an item alone from its state to the owner's accept: the lead runs the phases, records each guess, passes the plan gate with proceed, and stops at a stop rule. Use when the owner types /yolo with an id, a prompt, or nothing.
write-walkthrough
Write walkthrough.md, the explanation of finished work: what works now in plain words, the changed files, where to start reading, the key code, the met criteria, how to try it, the risks. It is the source of the Walkthrough tab of the web app. Use after /qa, or for a question about the code.
wiki-tidy
Find what is wrong in the wiki: broken links, pages with no index line, lines too near the code, stale epic pages, topics with no source, two pages on one topic, adjectives with no example. Fix the mechanical part after one yes; list the rest. Use when the owner says tidy the wiki, or after many pages changed.
wiki-merge
Merge related wiki pages into one complete page: the pages of the features of one process or epic become one page with the flow from end to end. The old pages move to the archive after the owner's yes, and their links point at the new page. Use when the owner says merge these pages, or when wiki-tidy finds pages on one topic.
wiki-ask
Answer a question from the wiki: the index first, then only the pages whose line matches, an answer in a few lines with a link to each page. Use when the owner asks what the wiki says, or asks why or how about a known topic. Not to add a page: wiki-add.
wiki-add
Keep the lesson of a source in the wiki: a page in the shelf business/ or tech/ with its main points, a real example for each, the gotchas and the link of the source; written after the owner's yes. Use when the owner says add this to the wiki, keep this, or gives a PRD, a ticket, notes or an article to keep.