Caveat

Caveat

A caveat is a hazard met once. It is worth exactly one thing: the safeguard it buys.

The deliverable is two artifacts, always both. An entry in CAVEAT.md carrying the condition under which the hazard recurs, and a landed safeguard — a hook, a validation check, a workflow rule, or stated preventative guidance with a home. Recording without converting is the failure this skill exists to prevent; a ledger of war stories teaches nobody and warns nobody.

When this fires

• something behaved differently from how it reads — a command that succeeds while doing the wrong thing, a flag whose absence is a decision, a default nobody chose
• an exception was discovered: this works, except when
• a hazard was met that a later session would meet the same way
• an oops or mistake moment, where the workflow pauses here before continuing
• a review, audit or postmortem produced a "careful, X does Y" with nothing behind it

What this is not

The cycle — pause, record, remediate, continue

At an oops or mistake condition, the work in hand stops. It resumes after the safeguard, not after the entry.

1. Pause. Do not finish the step that surfaced the hazard. The details are never as sharp again as they are now, and a hazard written down later is written down as a story.

2. Name the hazard with its artifact. The command, the path, the output. "The gate was wrong" is not a hazard; "prisma migrate diff --shadow-database-url "$DATABASE_URL" drops the database it is printing a diff of" is.

3. State the condition under which it recurs. This is the field that earns the file. Write the state that reproduces it, not the story: "a promotion touches a key whose rows contain an escaped pipe", never "someone was careless". A reader must be able to ask whether that state is present, and get an answer.

4. Decide the safeguard's kind — and prefer the mechanical ones, in this order:

   Kind	Use when	Lands as
   hook	the hazard is an action to refuse before it happens	a matcher in .claude/hooks/, with its case in the guard's matrix
   check	the hazard is a state a predicate can see	a gate in the owner's gate list, built by mistake-to-gate §1–§9
   rule	competent people could disagree about a finding, so a gate would be disabled	rule text via rules-distill, at a paths:-scoped tier
   guidance	the condition is judgment and no predicate exists	the entry itself, plus the document whose reader meets the hazard

   Reaching for guidance first is the tell that step 2 stopped too early. Try to state the predicate; only when it cannot be stated is guidance the honest kind.

5. Land the safeguard, then write the entry. In that order, so the entry cites something that exists. A Safeguard: naming work not yet done is the thing the gate refuses.

6. Append the entry with the shape CAVEAT.md documents, and run the gate:

   bash .claude/scripts/mistakes-check.sh
   

   It refuses an entry with no Recurs when: and an entry with no Safeguard:, so the conversion step is a repository-state predicate rather than a sentence in this file. A skill whose only enforcement is prose gets skipped.

7. Continue the work that was paused, and say in the commit that it was.

Interoperating with oops and mistake-to-gate

One event can be both a caveat and a mistake. They are recorded in different files for a mechanical reason, and the boundary is not a matter of taste:

• MISTAKES.md is counted. A row carries a failure-mode key, and mistakes.py derives recurrence from those keys to decide when a mistake has happened often enough to become a rule.
• CAVEAT.md is not. No entry here carries a key. A second file able to hold one would make every count an undercount, silently — the ladder would stop firing for any key split across the two, and both files would look healthy (DEC-0092, and the ADR recorded with it).

So when an event is both, do both, in this order:

# the counted occurrence, which returns the M-id
python3 .claude/skills/mistake-to-gate/scripts/mistakes.py append . \
  --key '<class>/<predicate-slug>' --context '…' --artifact '…' --fix '…'

then write the caveat entry and cite that id in Related mistake:. The key stays in one file; the recurrence condition, the impact and the safeguard live here. When the key reaches its threshold, mistake-to-gate §11 owns the promotion — this skill does not.

A caveat with no occurrence is normal. A hazard met while reading, or met and avoided, has nothing to count and no Related mistake: line. That is the case that makes this a separate ledger rather than a column.

Failure modes

Checklist

• The work that surfaced the hazard is paused, not finished
• The hazard is named with its command, path or output — not as a category
• Recurs when: states a condition a reader can test for, not a retelling
• The safeguard's kind was chosen from the table, mechanical kinds tried first
• The safeguard is landed, and the entry cites it by path
• The entry carries every field CAVEAT.md documents, and no failure-mode key
• bash .claude/scripts/mistakes-check.sh is green
• Where the event was also an occurrence, MISTAKES.md holds the keyed row and the entry cites its id
• The paused work is finished, and the commit says the pause happened