--- name: before-you-claim description: Seven questions answered with evidence at the moment a change is written, one for each defect class this repo's fault register keeps recording — a sentence claiming what the code does not do, a check that cannot fail, a fix for the instance while the class stays open, a rule that lives in prose with no mechanism, a property measured once, a guard that reads a command's spelling instead of its operation, a number written into prose. Use this skill every time you add or edit a comment, a docstring, a `.md` document, a `--help` text, a `--selftest` case, a lint, a hook, a guard, an agent brief, `orchestrator.md`, or any rule addressed to an agent; every time you fix a fault from the register or a bug from the manifest; and every time you are about to write down a number, a timing, or "does not reproduce". It applies to the ordinary edit, not only the big one — the register's worst recurrences were one-line comments and one-word fixes. The answers end whatever you hand over — the commit message, or when there is no commit, the notes, the PR text, the message back to the orchestrator — as a `claims:` block; a hook in this repo refuses a commit on these surfaces without one. --- # Before you claim Every defect class below was written by an agent that had read the rules and was following them; the moment of writing had no question. This skill is the question — seven of them, each answered with something that can be *shown*. It holds no rule of its own: `no-silent-pass`, `writing-python` and `CLAUDE.md` say how; this asks *did you, on this change, and where is the evidence?* **Questions 1, 2, 5 and 7 are one line each because the evals said so.** Run against a baseline with no skill on 2026-09-12, twice and on two models, the arms tied on those four at full marks and separated on question 4 both times. They still get asked; they no longer get a paragraph. The runs and their grading are in `../before-you-claim-workspace/iteration-4/benchmark.json`. ## Two touches **Before the first edit**, one line: which questions this change will have to answer (`touches: 1, 3, 4`). The sweep, the mutation and the second measurement are cheap before the edit and expensive after; naming the question is what gets them done while they are cheap. **Before you say done**, the `claims:` block (shape at the end) — one line per question, each carrying the evidence you gathered or `n/a — `. It ends whatever leaves your hands: the commit message when you commit; otherwise your notes, the PR description, or the message back to the orchestrator. There is no "done except the block". A line that asserts where evidence should be ("yes, it fails", no red output shown) is the skill not being used. The hook that asks for the block sees `git commit` only after `&&`, after `;`, or at the start of the command — not one that begins its own line under a heredoc, and not `-F -`. Its silence is not a verdict. ## The seven questions **1. What does this sentence claim the code does — and where is the line that does it?** The `file:line`, or the sentence rewritten to say only what the code does. `scripts/claim-lines.py --tree ` lists the added prose that claims behaviour. **2. What breaks this check, and did I watch it break?** The mutation, the red output, the restore; for a guard, the over-fire mutation too, with the allow case going red. Purge `__pycache__` between cycles. "The suite is green" is not an answer — it was green before the case existed. `no-silent-pass` is the long form. **3. Is this the fix for the instance, or for the class — and where else does the class live?** Grep the **bare** shape — the word, the number, the token — in the same file first, then the tree, and narrow only after you have seen every hit: a grep narrowed by the words you expect beside it (`seventeen` filtered by `edge|debt`) never shows the sentence about something else carrying the same rot. Paste the grep and its hits verbatim, then account for **every hit**: fixed, or *left, because …*. A sweep that names none of what it left is half a sweep — the next reader cannot tell a site you judged from one you missed. **4. Does this rule live in prose, or in a mechanism?** For every `must`/`never`/`always` addressed to an agent: the hook, script, schema or lint that enforces it, named **in the rule's own sentence** — and if nothing does, the rule says so about itself, where its reader will see it: *"Nothing enforces this today; the orchestrator's own recorded run is the verdict either way."* The failure has one shape, and it is the shape that costs marks: the author builds the mechanism, puts it somewhere real — a drift lint, a README row, a test anchor — and never puts the sentence where the rule's reader is, so the brief handed to the executor still says only *never do this*. **The mechanism is not the answer; the sentence naming it, in the rule's own text, is.** Your notes are read once by one person; the brief is read by every agent it is handed to. **5. Did I measure this once, and could the window have lied?** Two runs with a deliberate gap, on the tree the claim is about, the spread written — or *measured once* beside the number, in the document. Readings that agree inside one quiet window are still one window. **6. Does this guard read what the command will *do*, or what it *says*?** The decision from the operation — the file set, the tool's semantics, the resolved path — never a pattern over the text or one tool's name; and the allow case proven quiet *before* the deny widens. This is the register's longest-running class, and it recurs because a pattern over text always looks finished: a commit guard that reads `&&` but not a newline, a history guard that refuses a heredoc whose only act is to write a file. Both were widenings of an earlier text pattern. The test is whether you can name the operation the decision reads. **7. Is this number derived by something, or written by me?** The command that re-derives it beside it, or the number deleted and the pointer kept. History with a date stays legal; `CONTRIBUTING.md`'s *Writing a count that is allowed* is the long form. A green build is not evidence — the lints cannot see a decimal, or tell a past-tense count from a present-tense one. Two rules about the register: a finding goes into it *before* the fix, never inline in an unrelated change, and the fix cites the constraint in the code, never the fault id; a wrong first diagnosis is corrected in place with a sentence saying it was wrong, never deleted. ## The block `claims:` alone on a line, then one line per question in order; a line may continue on indented lines. The hook checks presence and shape; the reviewer judges the answers. ``` claims: 1 2 3 4 , named in the rule's own sentence | rule says "unenforced because …" about itself | n/a — no rule to an agent> 5 6 7 ``` Filled in, from a real change (a guard taught to see an MCP read): ``` claims: 1 guard-secrets-read.py:1402-1414 is the branch the docstring describes; hooks.json:5 routes mcp__.* to it 2 branch removed → m1-m6 red (213/219) → restored 219/219; read-verb check dropped → m9, m10 (allow) red 3 grep -n 'tool == "' guard-secrets-read.py: 3 hits — Read, Grep, Bash, each already reading a resolved path; MCP joins them 4 n/a — no rule to an agent 5 n/a — no property recorded 6 decision = resolved `path`/`paths` against SECRET_PATH; allow: mcp read of README → no output, exit 0, shown before the deny widened 7 n/a — no number written ``` `references/questions.md` holds the long form of each question — why the class recurs, and examples from this repo of it being written and of it being avoided.