diff --git a/skills/decision-records/SKILL.md b/skills/decision-records/SKILL.md index 4d4cc8b..38dab2a 100644 --- a/skills/decision-records/SKILL.md +++ b/skills/decision-records/SKILL.md @@ -72,6 +72,29 @@ leaves is not a gap: `check` reads a counter `origin/main` holds as held rather the rebase closes the sequence. A number neither tree has still fails, and with no ref on disk both behave exactly as they did before. +## Authoring + +Copy `drafts/_template.md` — the only template. A record is born a draft, and `promote` is the only +door into `accepted/`: it mints the counter, flips the status, and rewrites the H1, so there is +nothing an accepted-record template would add except a way around sign-off. + +Write the ruling, not the debate: + +- **Cite, don't restate.** The full argument lives in the linked thread, memo, or log; the record + carries the decision, the live rationale, and pointers under References. +- **Delete a section with nothing to say.** A Rationale that repeats the Decision, an unargued + alternatives table, a padded consequences list — deletion beats padding, and the template marks + which sections may go. +- **Every sentence earns its place.** A flat sentence that states the fact beats a paragraph that + performs it; one flourish is a voice, a flourish per paragraph is a tell. +- **One decision per record.** A record that keeps growing is usually several rulings sharing a file + — split them. + +There is deliberately no length rule. A pure ruling often fits in a few dozen lines; a record that +also carries specification — in some repos the accepted record IS the spec of what shipped — +legitimately runs hundreds. Length is a symptom to weigh, not a number to police; what the bullets +above remove is padding, which shows up at every length. + ## Promoting drafts **Promotion requires explicit human sign-off.** Promoting is a finalizing, semi-irreversible act @@ -103,8 +126,8 @@ missing and regenerates `INDEX.md`. What it does: - **Symlinks** `/scripts/decisions.py` to this skill's copy, and **gitignores** that path (creating `.gitignore` if absent) — the symlink is machine-specific, so each clone recreates it with `install` rather than committing it. -- **Scaffolds** `docs/decisions/`: `accepted/`, `archived/`, `drafts/`, the two record templates, a - human `README.md`, and an agent-facing `AGENTS.md`. +- **Scaffolds** `docs/decisions/`: `accepted/`, `archived/`, `drafts/` with its template (the only + one), a human `README.md`, and an agent-facing `AGENTS.md`. - **Generates** `INDEX.md` (a build artifact, not a starter). - **Wires the root entry points** — when the repo has no root `README.md` or `AGENTS.md` (a fresh or empty repo), creates each as a placeholder linking the scaffold so people and agents discover it. diff --git a/skills/decision-records/scripts/decisions.py b/skills/decision-records/scripts/decisions.py index 571416a..39720b2 100644 --- a/skills/decision-records/scripts/decisions.py +++ b/skills/decision-records/scripts/decisions.py @@ -11,11 +11,10 @@ INDEX.md # GENERATED registry over accepted/ + archived/ README.md # human guide to the convention (scaffolded by install) AGENTS.md # agent rules: decisions are binding (scaffolded by install) - _template.md # decision-record template (numbered) accepted/ # ACCEPTED numbered decisions — flat; `type` is front-matter archived/ # RETIRED numbered decisions (superseded | deprecated) — flat drafts/ # WIP candidates — flat, 4-UPPERCASE-letter ids, NOT in INDEX - _template.md + _template.md # the ONLY template — records are born drafts threat-model.md # other repo docs stay siblings; still cross-ref decisions Lifecycle (there is NO "proposed" status — proposing is the *act* of opening a PR): @@ -1417,7 +1416,6 @@ def install(repo: Path) -> None: for src, dst in ( (skill / "templates" / "README.md", decisions_dir(docs) / "README.md"), (skill / "templates" / "AGENTS.md", decisions_dir(docs) / "AGENTS.md"), - (skill / "templates" / "_template.md", decisions_dir(docs) / "_template.md"), (skill / "templates" / "drafts" / "_template.md", drafts_dir(docs) / "_template.md"), ): if src.exists() and not dst.exists(): diff --git a/skills/decision-records/templates/README.md b/skills/decision-records/templates/README.md index 64d2778..6f74d45 100644 --- a/skills/decision-records/templates/README.md +++ b/skills/decision-records/templates/README.md @@ -43,7 +43,11 @@ why a decision changed. ## Authoring & cross-referencing -- Copy `_template.md` for a decision, or `drafts/_template.md` for a draft, and fill it in. +- Copy `drafts/_template.md` — the only template. A record is born a draft; promotion mints the + counter and is the only way into `accepted/`. +- **Write the ruling, not the debate.** Cite the argument, don't restate it; delete a section with + nothing to say; a record that keeps growing is usually several decisions sharing a file. Padding, + not length, is what to trim. - Mint a draft's 4-letter ID yourself (a mnemonic of the topic). Accepted records get the next global counter automatically when a draft is promoted. - Refer to another record by writing its ID inline — the tooling renders IDs as links and keeps them diff --git a/skills/decision-records/templates/_template.md b/skills/decision-records/templates/_template.md deleted file mode 100644 index 049ace3..0000000 --- a/skills/decision-records/templates/_template.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Decision record — front-matter is machine-readable; keep it accurate. -# Filename: NNNN-kebab-title.md (the counter, then a kebab title — no type in the name). -# Identity = the counter `id` below: permanent, the only thing cross-references use. -# Authoring, promotion, linking, and validation are the decision-records skill's job — -# this template is just the record's shape. -id: "0000" # global counter, quoted to keep the zero-pad -title: Short imperative title -type: architecture # an open lowercase slug (architecture, product, security, …) -status: accepted # accepted | deprecated | superseded -date: YYYY-MM-DD -deciders: [trung] -summary: One sentence describing the decision. -tags: [] # e.g. [access-control, retrieval, orchestrator] -relates_to: [] # related record IDs, e.g. ["0001", "0003"] -supersedes: # ID this replaces, or blank -superseded_by: # ID that replaces this, or blank ---- - -# {id} — {title} - -## Context - -What forces are at play? What problem or tension prompted this decision? State the constraints as -they actually were at decision time. Don't sanitize. - -## Decision - -The decision in one or two sentences, active voice ("We will …"). Binding once `accepted` — course -changes only by supersession. - -## Rationale - -Why this option over the others, given the context above. - -## Alternatives considered - -| Option | Why not | -| :----- | :------ | -| … | … | - -## Consequences - -**Positive** - -- … - -**Negative / accepted costs** - -- … - -**Risks & open questions** - -- … - -## References - -- Threads, specs, external sources, and related records by ID (e.g. `0001`). diff --git a/skills/decision-records/templates/drafts/_template.md b/skills/decision-records/templates/drafts/_template.md index 8c69a17..18c94b0 100644 --- a/skills/decision-records/templates/drafts/_template.md +++ b/skills/decision-records/templates/drafts/_template.md @@ -1,8 +1,11 @@ --- -# Draft — a decision candidate (WIP). Same shape as a decision record, so promotion is -# mechanical; it just carries a 4-letter ID and status: draft, and lives in drafts/. +# Draft — a decision candidate (WIP), and the ONLY template: a record is born a draft, +# and `promote` is the only door into accepted/ (it mints the counter and flips status). # Filename: AAAA-kebab-title.md (AAAA = the 4 UPPERCASE letters of `id` below). # Promotion, linking, and validation are the decision-records skill's job. +# Write the ruling, not the debate: cite the argument (References), don't restate it. +# Delete a section with nothing to say — padding, not length, is what to trim — and a +# record that keeps growing is usually several rulings sharing a file. id: ABCD # REQUIRED: 4 UPPERCASE letters, a mnemonic of the topic title: Short imperative title type: architecture # an open lowercase slug (architecture, product, security, …) @@ -20,38 +23,36 @@ superseded_by: # ID that replaces this, or blank ## Context -What forces are at play? What problem or tension prompts this decision? State the constraints as -they actually are. Don't sanitize. +The tension that forces a decision, in a few sentences, as it actually is. Don't sanitize, and don't +narrate history the References already carry. ## Decision -The proposed decision in one or two sentences, active voice ("We will …"). Binding once promoted and +The decision in one or two sentences, active voice ("We will …"). Binding once promoted and `accepted` — course changes only by supersession. ## Rationale -Why this option over the others, given the context above. +Only what the Decision doesn't already imply — why this over the alternatives. Delete the section +when it would just repeat the Decision. ## Alternatives considered +Only options genuinely argued — never pad the table. Delete the section when nothing else was on the +table. + | Option | Why not | | :----- | :------ | | … | … | ## Consequences -**Positive** - -- … - -**Negative / accepted costs** - -- … - -**Risks & open questions** +What this makes better, worse, or riskier — one list, only lines someone will act on. Open questions +and pending follow-up rulings live here too. - … ## References -- Threads, specs, external sources, and related records by ID (e.g. `0001`, `TIER`). +Records by ID (e.g. `0001`, `TIER`), threads, memos, sources — where the full argument lives. Delete +the section when there are none. diff --git a/skills/decision-records/tests/test_decisions.py b/skills/decision-records/tests/test_decisions.py index ac7e15f..144e28f 100644 --- a/skills/decision-records/tests/test_decisions.py +++ b/skills/decision-records/tests/test_decisions.py @@ -808,11 +808,12 @@ def test_install_scaffolds_fresh_repo(tmp_path): "decisions/archived/.gitkeep", "decisions/README.md", "decisions/AGENTS.md", - "decisions/_template.md", "decisions/drafts/_template.md", "decisions/INDEX.md", ): assert (docs / p).exists(), p + # ONE template: records are born drafts, so no accepted-record template is scaffolded + assert not (docs / "decisions/_template.md").exists() assert decisions.main(["check"], root=docs) == 0 # scaffolded repo is valid immediately # gitignores the machine-specific symlink (creating .gitignore in an empty repo)