agentleFS
enixenix/kube-image-keeper/.claude/skills/decision-note/SKILL.md

decision-note

Skill759 starsChanged 21 days agoMITView on GitHub

Write a decision note under notes/ (filter, numbered file, index line)

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
  1. Distinctive:

    If none holds, say so, draft the commit body that carries the "why" instead, and stop.

    line 23
  2. Very specific:

    Run ls notes/. The next number is the highest existing NNNN- plus 1, on 4 digits.

    line 33
  3. Very specific:

    Use draft if the user says the shape is not settled.

    line 42
  4. Very specific:

    Update the index line of notes/README.md if the decision in one line changed.

    line 69
  5. Very specific:

    When the shape stops moving, set the status to decided: the note is frozen from then on.

    line 70
  6. Very specific:

    Write the new note NNNN as above.

    line 76
  7. Very specific:

    When only one section of OOOO changes, supersede that section alone: the new note restates the decision of that section, and the rest of …

    line 81

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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. Use draft if 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 ## Writing section of AGENTS.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 note NNNN instead.

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:
    1. Set **Amended:** YYYY-MM-DD between Date and Status (add it, or update it to today).
    2. 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 ...)*.
    3. Update the index line of notes/README.md if the decision in one line changed.
    4. When the shape stops moving, set the status to decided: the note is frozen from then on.
  • decided: frozen, never rewritten; supersede it with a new note.

To supersede note OOOO:

  1. Write the new note NNNN as above. Its Decision restates the whole decision now in force, not a diff, so the reader never needs OOOO; start it with Supersedes [OOOO](./OOOO-slug.md).
  2. Its Why gives what changed since OOOO. The old decision becomes a Rejected line: it was weighed, and lost.
  3. When only one section of OOOO changes, supersede that section alone: the new note restates the decision of that section, and the rest of OOOO stays in force.
  4. 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.
  5. In the index, keep the line of OOOO and end it with Superseded by [NNNN](./NNNN-slug.md). (or Section "<heading>" superseded by [NNNN](./NNNN-slug.md).).
  6. 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.md

Fix by hand what it could not fix, until task lint-markdown -- <same files> passes. Do not commit: the user reviews the note first.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.