doc-adr
/octopus:doc-adr creates a numbered Architecture Decision Record
from the project template. Use it any time you make a non-trivial
technical decision — during design, implementation, or after a
post-mortem — so the reasoning is captured where future contributors
can find it.
What it solves
Technical decisions get made constantly, but the reasoning behind them is rarely written down. Six months later, someone reads the code and wonders why the team chose this data model, this library, or this protocol boundary. Without an ADR, the answer is a Slack search or a meeting invite.
An ADR changes that. It’s a short, durable record: what was the
context, what was decided, what alternatives were rejected, and what
the consequences are. doc-adr handles the mechanical work —
numbering, dating, and placing the file — so the friction of
capturing a decision is close to zero.
How it works
- Resolves the slug — from the argument you pass, or by asking you to describe the decision in a few words.
- Scans
docs/adrs/to find the current highest number and increments it (zero-padded to three digits; starts at001for a fresh project). - Reads the ADR template, fills in the number, date, and title, and
writes the file to
docs/adrs/<number>-<slug>.md. - Reports the file path and ADR identifier, and reminds you to fill in the Context, Decision, and Consequences sections.
- If a related spec exists in
docs/specs/, suggests linking the ADR from the spec’s Context for Agents section.
Usage & parameters
/octopus:doc-adr [slug][slug]— kebab-case description of the decision (e.g.use-postgresql,parser-strategy). If omitted, the command asks before proceeding.