recording-decisions
riekelt/technical-writer
Record architectural decisions and choice rationale in durable ADR and decision-log formats.
What is recording-decisions?
Captures decisions that would otherwise live only in chat—architectural choices, trade-offs, and rejections—in append-only ADR (Architecture Decision Record) and decision-log formats. Use whenever a choice has been made and needs durable recording, or when an existing decision is superseded by new context.
- Generates ADRs in Nygard format with context, decision, consequences, and alternatives considered
- Creates lightweight decision-log entries for smaller, running choices
- Enforces append-only immutability: accepted decisions cannot be edited, only superseded by new dated entries
- Requires explicit negative consequences and strongest arguments for rejected alternatives
- Captures why decisions were made, not just what was decided
- Marks unknowns and failed investigations as explicit results
How to install recording-decisions
npx skills add https://github.com/riekelt/technical-writer --skill recording-decisions- The `technical-writing` skill must be installed (hard rules, truth rules, style)
How to use recording-decisions
- 1.Identify a decision that has been made and needs recording (or an existing decision now superseded)
- 2.Decide whether it warrants a full ADR (architecture-level consequences) or a lightweight decision-log entry
- 3.For ADRs: provide context (forces at play), the decision itself, positive/negative/neutral consequences, alternatives with their strongest arguments, and references
- 4.For decision-log entries: state the decision as an imperative, explain why in bullet points, and note what was rejected instead
- 5.Commit the dated entry to the repository before citing it in chat or documentation
Use cases
- Recording an architectural choice made in a PR comment or chat thread before it's lost
- Documenting a trade-off between two technical approaches with full reasoning
- Creating a new ADR entry when circumstances change and an old decision is superseded
- Maintaining a running log of smaller engineering choices (naming conventions, deployment strategies, tooling selections)
- Capturing why a rejected alternative was not chosen, with its strongest case stated
- Technical leads and architects documenting system design decisions
- Engineering teams maintaining decision history for onboarding and context
- Project leads recording trade-offs and rationale for future reference
- Anyone needing to explain why a choice was made to someone who wasn't in the original discussion
recording-decisions FAQ
Use a full ADR for decisions with architecture-level consequences that will shape the system long-term. Use decision-log entries for the running stream of smaller choices (naming, deployment strategy, tooling). Both are append-only.
No. Accepted decisions are immutable. If circumstances change or the decision was wrong, create a new dated entry that supersedes the old one. The only permitted edit to an accepted ADR is adding 'Superseded by ADR-XXX' to its Status line.
You must state the strongest argument for each alternative considered, even if it's weak. Rejecting an alternative without stating its best case is a strawman and violates the format. If you cannot find a good argument, that signals you may not have understood the alternative.
No. Record only decisions that have been made and accepted. If a choice is still being argued, use the `writing-design-docs` skill instead; once accepted, that Why & What box becomes the ADR.
Any choice that would otherwise live only in chat: trade-offs resolved in PR comments, 'we decided X instead of Y' statements, rationales explained twice, or unrecorded architectural choices. Record the smallest complete decision, not a transcript.
Full instructions (SKILL.md)
Source of truth, from riekelt/technical-writer.
name: recording-decisions description: Use when a decision needs recording - an ADR, a decision log entry, or when someone asks to write down why something was chosen, rejected, or superseded. Encodes the ADR and decision-log formats. Use whenever a choice was made that would otherwise live only in chat, even if nobody says "ADR".
Recording decisions
REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).
Overview
Two formats, by weight: a full ADR for a decision with architecture-level consequences; a decision log entry for the running stream of smaller choices. Both are append-only: an accepted decision is immutable; new context is a new entry that supersedes the old one.
When to invoke, and not
Invoke when a choice has been made and needs recording, when someone asks "write down why we did this", or when an existing decision is superseded. Do NOT invoke for a decision still being argued (that is writing-design-docs; its Why & What box becomes the ADR once accepted).
Also invoke on the signals that an unrecorded decision is passing by: "we decided X instead of Y", "let's just go with", a trade-off resolved in a PR comment or chat thread, or a rationale someone has now explained twice. Each is a decision living in a non-durable place; offer to record it.
Record the decision before citing it. A chat session is not a durable source. Put the dated substance in the log, quote the decider where wording matters, commit the entry, then cite it. Record the smallest complete decision, not a transcript.
ADR
Nygard format. One decision per ADR.
# ADR-[number]: [short title of the decision]
| | |
|---|---|
| **Status** | Proposed / Accepted / Superseded by ADR-XXX |
| **Date** | YYYY-MM-DD |
| **Deciders** | [who took part] |
## Context
[The forces at play: technical, organizational, political. What must be solved.
Factual, without giving away the decision.]
## Decision
[What was decided. Active voice: "We release on tags", not "it was decided that".]
## Consequences
**Positive:** [what gets easier]
**Negative:** [what gets harder, which trade we accept]
**Neutral:** [what changes without being better or worse]
## Alternatives considered
**[Alternative]** - For: [...] Against: [...] Why not chosen: [...]
## References
[Evidence, related decisions, measurements]
Negative is mandatory and may not be empty. Each alternative carries its strongest argument for; a rejection without it is a strawman.
The sole permitted edit to an accepted ADR is its Status line gaining "Superseded by ADR-XXX". An objection raised but never answered goes in at full strength as a negative consequence with a named owner: the writer never invents a rebuttal and never withholds a decision its owner has declared. Names unknown at writing time are marked fill-before-filing, because a filed record carries real people.
Decision log (lightweight)
For the running log a full ADR would kill. Cheap enough to maintain:
## YYYY-MM-DD
### [Decision stated as an imperative sentence]
[One paragraph: the rule.]
Why:
- [reason]
- [reason]
Instead of: [rejected option] - [why not]
Rules
- Append-only. A wrong entry gets a new dated entry that supersedes it, never an edit. Convert relative dates to absolute.
- Record the why, not only the what.
- When a written rule and shipped reality have diverged, record which one the team intended. Every doctrine document states what it owns and what it leaves to others.
- Scope guard at the top when a sibling could overlap: "product ideas live in ROADMAP.md; this file is for engineering decisions."
- Capture negative results and unknowns explicitly: "four theories, four disproved, cause not found" is a result. A search returning nothing is a result.
Related skills
More from riekelt/technical-writer and the wider catalog.
reviewing-technical-prose
Systematic technical prose review with severity mapping, findings format, and delivery checklist.
technical-writing
House style and structural rules for technical documents: clear, sourced, single-source-of-truth prose.
writing-changelogs
Write clear, honest changelog entries and release notes following structured conventions.
writing-design-docs
Structure proposals, RFCs, and design docs with decision boxes, cost accounting, and completeness checks.
writing-issues
Write tracker items that survive without you—clear outcomes, testable acceptance criteria, and named owners.
writing-postmortems
Write blameless, evidence-based postmortems and incident reports that outlive the crisis.