AGENT SKILL

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

  1. 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).
  2. Isolate. Run the smallest test or command that still fails. Remove what does not matter: other tests, other files, other input.
  3. 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.
  4. 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.
  5. Fix the cause. Do not widen a test, skip a test or add a retry.
  6. 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 ~/.claude or in an area you do not own.

04 同仓库更多 Skills

lamtran8401
lamtran8401/nook

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.

★ 0
lamtran8401
lamtran8401/nook

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.

★ 0
lamtran8401
lamtran8401/nook

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.

★ 0
lamtran8401
lamtran8401/nook

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.

★ 0
lamtran8401
lamtran8401/nook

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.

★ 0
lamtran8401
lamtran8401/nook

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.

★ 0