decision-note
Skill759 starsChanged 21 days agoMITView on GitHub
Write a decision note under notes/ (filter, numbered file, index line)
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- acceptance-scenariosSkill
- e2e-specSkill
- pull-requestSkill
- release-acceptanceSkill
- release-notesSkill
- test-outlineSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 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.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
If none holds, say so, draft the commit body that carries the "why" instead, and stop.
- Very specific: line 33
Run ls notes/. The next number is the highest existing NNNN- plus 1, on 4 digits.
- Very specific: line 42
Use draft if the user says the shape is not settled.
- Very specific: line 69
Update the index line of notes/README.md if the decision in one line changed.
- Very specific: line 70
When the shape stops moving, set the status to decided: the note is frozen from then on.
- Very specific: line 76
Write the new note NNNN as above.
- Very specific: line 81
When only one section of OOOO changes, supersede that section alone: the new note restates the decision of that section, and the rest of …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Write a decision note
Decision to record: $ARGUMENTS. The rules come from notes/README.md
and 0005; if this skill disagrees, they win.
1. Apply the filter
A note is warranted only when at least one of these holds:
- the decision constrains work beyond the change that implements it;
- it rejects an alternative that someone will plausibly propose again;
- it has no single commit to live in (process, architecture, spec interpretation, repository-wide tooling).
If none holds, say so, draft the commit body that carries the "why" instead, and stop.
2. Record only deliberation that happened
Take the alternatives from the conversation. If they are not there, ask the user which ones were actually weighed and why they lost. Never invent a Rejected line to fill the template: no alternative weighed means no Rejected section.
3. Number and name the file
Run ls notes/. The next number is the highest existing NNNN- plus 1, on 4 digits. The
slug is short and kebab-case: notes/NNNN-short-slug.md.
4. Write the note
Copy the shape of notes/0009-rbac-rules-from-markers-bindings-from-chart.md:
- H1
# NNNN — <title>(the em dash is the notes' convention, keep it). **Date:** YYYY-MM-DD · **Status:** decided, with today's date in digits. Usedraftif the user says the shape is not settled.**Decision:**first, stating the decision itself. One sentence, a few more only for the exceptions the reader must know.**Why:**in 2 to 4 bullets, each a fact the reader could not guess.**Rejected:**one bullet per alternative actually weighed: the alternative, a colon, why it lost.- A Why or Rejected bullet that rests on a spec section, an issue or a PR links it:
a relative link inside the repository (
../docs/v3/spec.md#<heading-slug>), the URL for an issue or a PR. - Under 25 lines in total. Follow the
## Writingsection ofAGENTS.md: no padding, no restating the title.
Status values:
draft: work in progress, may be incomplete or dropped; edit freely.active: the reference in force, details still expected to move; edit in place.decided: frozen; typo fixes only, changed only by a superseding note.superseded by NNNN: kept for history; read noteNNNNinstead.
How a note changes depends on its status (0002, working agreements):
draft: edit freely, no trace needed.active: amend in place, the way 0002 and 0003 were:- Set
**Amended:** YYYY-MM-DDbetween Date and Status (add it, or update it to today). - Open each changed passage with
*(Amended YYYY-MM-DD:)*. When it reverses what the note first said, say so:*(amendment vs the original plan, which ...)*. - Update the index line of
notes/README.mdif the decision in one line changed. - When the shape stops moving, set the status to
decided: the note is frozen from then on.
- Set
decided: frozen, never rewritten; supersede it with a new note.
To supersede note OOOO:
- Write the new note
NNNNas above. Its Decision restates the whole decision now in force, not a diff, so the reader never needsOOOO; start it withSupersedes [OOOO](./OOOO-slug.md). - Its Why gives what changed since
OOOO. The old decision becomes a Rejected line: it was weighed, and lost. - When only one section of
OOOOchanges, supersede that section alone: the new note restates the decision of that section, and the rest ofOOOOstays in force. - In
OOOO, change only the status:**Status:** superseded by [NNNN](./NNNN-slug.md), or**Status:** decided; section "<heading>" superseded by [NNNN](./NNNN-slug.md)for a single section. Date and body stay as they are. - In the index, keep the line of
OOOOand end it withSuperseded by [NNNN](./NNNN-slug.md).(orSection "<heading>" superseded by [NNNN](./NNNN-slug.md).). - Point the live references to
NNNN:grep -rn 'OOOO' AGENTS.md CONTRIBUTING.md .claude. References inside other notes are history; leave them.
Skeleton:
# NNNN — <title>
**Date:** YYYY-MM-DD · **Status:** decided
**Decision:** <the decision, in one sentence>.
**Why:**
- <reason the reader could not guess>
- <second reason>
**Rejected:**
- <alternative>: <why it lost>.5. Add the index line
Append one entry to the ## Index of notes/README.md, in number order, same shape as the
others: - [NNNN — <title>](./NNNN-slug.md): <the decision in one line>. State the
decision, not the topic. Wrap at about 90 columns with a 2-space continuation indent.
6. Link back
Remind the user that the commit implementing the decision references the note: the note
number in the commit body, and [NNNN](./notes/NNNN-slug.md) in AGENTS.md or the
matching .claude/rules/ file when the decision constrains agents.
7. Lint
task lint-markdown-fix -- notes/NNNN-slug.md notes/README.mdFix by hand what it could not fix, until task lint-markdown -- <same files> passes. Do not commit: the user reviews the note first.
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.

