Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions skills/decision-records/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -103,8 +126,8 @@ missing and regenerates `INDEX.md`. What it does:
- **Symlinks** `<repo>/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.
Expand Down
4 changes: 1 addition & 3 deletions skills/decision-records/scripts/decisions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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():
Expand Down
6 changes: 5 additions & 1 deletion skills/decision-records/templates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
58 changes: 0 additions & 58 deletions skills/decision-records/templates/_template.md

This file was deleted.

33 changes: 17 additions & 16 deletions skills/decision-records/templates/drafts/_template.md
Original file line number Diff line number Diff line change
@@ -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, …)
Expand All @@ -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.
3 changes: 2 additions & 1 deletion skills/decision-records/tests/test_decisions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading