before-you-claim
Skill4 starsChanged 3 months agoMITView on GitHub
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.
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- choosing-what-to-optimizeSkill
- grill-meSkill
- no-silent-passSkill
- orchestrating-parallel-workSkill
- refactoring-the-assembled-uiSkill
- reproducing-ci-locallySkill
- running-resumable-sync-jobsSkill
- verifying-external-behaviorSkill
- writing-cssSkill
- writing-javascriptSkill
- writing-pythonSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Every defect class below was written by an agent that had read the rules and was following them.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 — <reason>. 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 <diff> --tree <checkout> 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 <file:line that does what the sentence says | rewritten to say only what the code does | n/a — no behaviour claimed>
2 <mutation → red output → restored; allow case → red under over-fire | n/a — no check touched>
3 <grep for the bare shape: N hits — each fixed, or left because … | n/a — not a fix of a reported defect>
4 <enforced by <hook/script>, named in the rule's own sentence | rule says "unenforced because …" about itself | n/a — no rule to an agent>
5 <two runs, gap, spread | "measured once" beside the number in the document | n/a — no property recorded>
6 <decision reads the operation, not the text; allow case proven quiet first | n/a — no guard>
7 <command beside the number | number deleted, pointer kept | n/a — no number written>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 writtenreferences/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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

