Decision Record Skill
Turns a judgment call that's still only in someone's head — or in a PR description that will scroll out of sight — into a durable markdown file the next reader can find. The record captures why a choice was made and what the real alternative was, so the reasoning survives the person who had it.
The format is fixed, not negotiated: a dated filename, a declarative one-sentence title with no leading number, no Status field, and exactly four sections. That's the whole point — a record written by this skill looks the same in every repo, so a reader who has seen one can read them all. See references/format.md for each rule and why it's that way, including what to do when a repo already keeps records in a different shape.
Mutation posture. Writing the file is the point of this skill, so creating or editing a record under docs/decision-records/ doesn't need a separate confirmation once the user has asked for one. The mandate stops there: it never pushes, opens a PR, or edits the code the record is about. Committing the record is a plain docs: commit — see references/writing.md.
When a Record Is Warranted
Write one when the change is a choice with a real alternative that the code alone won't explain to a future reader:
- An output contract — where something writes, what its one write is, what it deliberately never touches.
- A naming, layout, or configuration convention that other work will have to follow.
- A workflow that deliberately deviates from an existing precedent in the same codebase.
- A lens, dimension, or rule added to a rubric or checklist.
- A resolution order for ambiguous input (which signal wins when two disagree).
- A dependency, protocol, or storage choice picked over a named competitor.
Do not write one for: a routine edit, a typo or wording fix, anything already stated plainly in the repo's agent instructions or contributing guide, or a decision with no real alternative anyone would have picked instead. A record that documents a non-choice trains readers to skip the directory.
If you're unsure, the test is: could a competent contributor six months from now reasonably undo this, not knowing what you knew? If yes, write it.
The Shape at a Glance
docs/decision-records/YYYY-MM-DD--kebab-slug.md
# <One declarative sentence stating the decision>
- **Date:** YYYY-MM-DD
## Context
## Decision
## Consequences
## Related
Reference Files (read these on demand)
| Task |
Read |
Filename and slug rules, the title shape, the four sections, why no number and no Status |
references/format.md |
| What goes in each section, sourcing the "why", editing and superseding, the commit |
references/writing.md |
Copyable templates live in assets/:
assets/decision-record.template.md — an empty record with each section's requirements as comments
Critical Gotchas
- Never invent the "why." If the rationale isn't in the conversation, the PR description, the issue, or the code, ask the author — or leave a
TODO(author): line naming exactly what's missing. A confidently wrong rationale is worse than no record at all, because it gets cited.
- A changed decision is a new record, never a rewrite. Editing a past record to match hindsight destroys the only evidence of what was actually known at the time. Write a new one and link back from its
## Related.
- No leading number in the title, and no
Status field. Both are common in other ADR conventions and both are excluded here for concrete reasons — references/format.md.
- Context must show the decision was real. State the failure mode on both sides of the choice. A Context that only justifies the option already picked is marketing, not a record.
- Link siblings by relative filename, never by number.
[2026-08-21--base-branch-resolution](2026-08-21--base-branch-resolution.md), not "see ADR 4".
- Don't write a record for a non-choice. Say plainly that none is warranted and why, rather than producing one to satisfy the request.
- Placeholders only. A record explaining an infrastructure or auth decision must not carry real hostnames, tokens, or credentials into version control.
- The repo's existing records don't override this format. If they use a different shape, say so out loud and still write the shape above — see
references/format.md → "When the repo already has records".
1---2name: decision-record3description: Writes or updates an architecture decision record (ADR) as a dated markdown file under docs/decision-records/ — a one-sentence declarative title with no leading number and no Status field, and the four sections Context, Decision, Consequences, Related. Use when a change makes a real judgment call with a defensible alternative that the code alone won't explain, when asked to "record this decision", "write an ADR", or "document why we chose this", or when a review flags an undocumented decision. Never invents a rationale — it asks when the "why" isn't known.4---56# Decision Record Skill78Turns a judgment call that's still only in someone's head — or in a PR description that will scroll out of sight — into a durable markdown file the next reader can find. The record captures **why** a choice was made and what the real alternative was, so the reasoning survives the person who had it.910The format is fixed, not negotiated: a dated filename, a declarative one-sentence title with no leading number, no `Status` field, and exactly four sections. That's the whole point — a record written by this skill looks the same in every repo, so a reader who has seen one can read them all. See `references/format.md` for each rule and why it's that way, including what to do when a repo already keeps records in a different shape.1112**Mutation posture.** Writing the file is the point of this skill, so creating or editing a record under `docs/decision-records/` doesn't need a separate confirmation once the user has asked for one. The mandate stops there: it never pushes, opens a PR, or edits the code the record is about. Committing the record is a plain `docs:` commit — see `references/writing.md`.1314## When a Record Is Warranted1516Write one when the change is a **choice with a real alternative** that the code alone won't explain to a future reader:1718- An output contract — where something writes, what its one write is, what it deliberately never touches.19- A naming, layout, or configuration convention that other work will have to follow.20- A workflow that deliberately deviates from an existing precedent in the same codebase.21- A lens, dimension, or rule added to a rubric or checklist.22- A resolution order for ambiguous input (which signal wins when two disagree).23- A dependency, protocol, or storage choice picked over a named competitor.2425Do **not** write one for: a routine edit, a typo or wording fix, anything already stated plainly in the repo's agent instructions or contributing guide, or a decision with no real alternative anyone would have picked instead. A record that documents a non-choice trains readers to skip the directory.2627If you're unsure, the test is: *could a competent contributor six months from now reasonably undo this, not knowing what you knew?* If yes, write it.2829## The Shape at a Glance3031```32docs/decision-records/YYYY-MM-DD--kebab-slug.md33```3435```markdown36# <One declarative sentence stating the decision>3738- **Date:** YYYY-MM-DD3940## Context4142## Decision4344## Consequences4546## Related47```4849## Reference Files (read these on demand)5051| Task | Read |52|---|---|53| Filename and slug rules, the title shape, the four sections, why no number and no `Status` | `references/format.md` |54| What goes in each section, sourcing the "why", editing and superseding, the commit | `references/writing.md` |5556Copyable templates live in `assets/`:57- `assets/decision-record.template.md` — an empty record with each section's requirements as comments5859## Critical Gotchas60611. **Never invent the "why."** If the rationale isn't in the conversation, the PR description, the issue, or the code, ask the author — or leave a `TODO(author):` line naming exactly what's missing. A confidently wrong rationale is worse than no record at all, because it gets cited.622. **A changed decision is a new record, never a rewrite.** Editing a past record to match hindsight destroys the only evidence of what was actually known at the time. Write a new one and link back from its `## Related`.633. **No leading number in the title, and no `Status` field.** Both are common in other ADR conventions and both are excluded here for concrete reasons — `references/format.md`.644. **Context must show the decision was real.** State the failure mode on *both* sides of the choice. A Context that only justifies the option already picked is marketing, not a record.655. **Link siblings by relative filename, never by number.** `[2026-08-21--base-branch-resolution](2026-08-21--base-branch-resolution.md)`, not "see ADR 4".666. **Don't write a record for a non-choice.** Say plainly that none is warranted and why, rather than producing one to satisfy the request.677. **Placeholders only.** A record explaining an infrastructure or auth decision must not carry real hostnames, tokens, or credentials into version control.688. **The repo's existing records don't override this format.** If they use a different shape, say so out loud and still write the shape above — see `references/format.md` → "When the repo already has records".
eagerworks