Card hygiene — durable cards with headings that carry their meaning
The principle
A durable artifact survives across chat sessions, can be referenced without ambiguity, keeps its rules without re-explaining them, has detectable violations, and has action items reachable in one scan. Chat is ephemeral; cards and task rows are what last.
Headings that carry their meaning
Every heading carries a one- or two-line summary of its section:
## §N Section name — who/what/how, key facts, key numbers
A reader scanning only the table of contents should be able to predict what each section says and decide whether to dive in. Generic headings like "Implementation plan" are banned. They name a topic without saying anything.
Self-test: would deleting the summary change a reader's decision to dive in? If yes, the heading is doing its job.
Actions at the top
On an actionable card, the actions come immediately after the one-line summary, numbered flat 1…N (no nested numbering, no letters). They can be referenced unambiguously as [card-id]:N. The reasoning sits below; the what is reachable in one scan.
Read only the section you need
Every card body gets a table of contents on save. An agent can fetch one named section, not the whole card, so a 600-line spec costs a few hundred tokens to consult.
Summaries in tiers
- T1 — one line.
- T2 — a table of contents that includes each section's summary.
- Full — the body.
An agent loads exactly as much as the task needs. A local model can check that every heading really matches its body, and short cards skip the machinery entirely.