About documenting-decisions
A skill for recording consequential development choices in code and summarizing them for review. It helps developers and coding agents distinguish review-worthy decisions from routine changes, with guidance for ADRs and ticket reconciliation.
Key features
- 01Six decision checkpoint tags
- 02Decision log for pull requests
- 03ADR follow-up guidance
- 04Ticket reconciliation after completion
- 05Diff hunk classification mode
Use cases
- 01Flagging architecture or interface changes
- 02Summarizing security and irreversible changes
- 03Reviewing a diff by decision category
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/documenting-decisionsin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
README.mdreferences/canary-signals.mddecision-markers.mdirreversible-operations.mdmarker-examples.mdpre-approval-gate.mdscope-interpretation.mdsecurity-protocol.mdDetails
From the project READMEDocumenting Decisions
Checkpoint tags
| Tag | When to mark |
|---|---|
ARCH | New abstractions, deps, data models, component boundaries — anything that shapes long-term structure. |
SCOPE | You resolved an ambiguity in the task by choosing an interpretation. |
IFACE | Changed a public API, config schema, CLI flag, env var, or wire format. |
SEC | Touched auth, crypto, permissions, network exposure, or input validation. |
IRREV | Created a migration, data deletion, deployment trigger, or external side effect. |
NOVEL | No existing repo pattern to follow — you interpolated from training data. |
Do not mark routine changes (pattern-following, boilerplate, refactoring).
Format
See this skill's references/ decision-markers.md and (if needed) marker-examples.md.
After task completion
Generate decision log from markers in changed files and add to PR description:
## Decisions requiring review
- **TAG** `file:line` — explanation
## Routine (skip review)
[One-line summary]
If an ARCH or IRREV marker meets the writing-adrs bar (hard to reverse, surprising without context, result of a real trade-off), also write the ADR per that skill.
Reconcile driving ticket
Work driven by ticket → update it before close: fold in deviations, mid-session scope, decisions above (or their ADR/glossary refs). Per to-tickets reproducibility invariant: replayed issue stream builds final state, not first draft.
Diff classification mode
When user requests review of diff, classify each hunk as one of the six tags or ROUTINE. Present as File: path — TAG with line ranges.
Reference files
references/canary-signals.md— CI scripts for automated checkpoint detection (repo setup, not runtime).references/marker-examples.md— example markers in multiple languages.- other files in references are only relevant if explicitly mentioned in AGENTS.md or requested by the user.