new-adr

name

new-adr

description

Author a new ADR — record a DECISION (what the system must do, or how it is built) in a documentation-led repo. Picks the next contiguous number, chooses the shape (capability vs technology), fills the template, sets status Proposed, regenerates INDEX, updates domain READMEs, handles supersede/deprecate linkage, commits. Use when the user says "add an ADR", "new ADR", "record a decision", "create an architecture decision record", or invokes /new-adr. NOT for queueing a unit of work against an existing decision (use /new-plan), NOT for recording a reusable rule, practice, or naming/process standard (use /add-convention), and NOT for a living capability spec on the decisions+specs record model (use /new-spec).

new-adr

Author one new ADR, consistent with this repo's conventions.

Step 0 — Preconditions and context

1. Confirm the repo is bootstrapped: AGENTS.md, CONVENTIONS.md, and an adr/ directory with at least adr/0000-template.md must exist. If not, stop and offer to run the bootstrap skill first.
2. Read CONVENTIONS.md to learn this repo's choices: ADR shape (single vs. capability/technology split and the cutoff number), status lifecycle, language mandate (if any), whether domains/ groupings exist (and, if so, which domain this ADR belongs to — ask if it isn't obvious), the multi-agent mode, and the artefact root (default: repository root) — resolve adr/ and INDEX.md against it (AGENTS.md/CLAUDE.md stay at the repo root).
3. Read INDEX.md and ls adr/ to learn existing numbers and titles.
4. If a federation.md exists, this repo is part of a multi-repo product. Note the identity scheme and the home it records — they govern numbering and cross-repo references below.

Step 0.5 — Assessment (run first)

Run the shared assessment protocol before authoring:

• Depth selector first. Ask how deep this assessment should go: express — every choice takes its recommended default; only questions with no derivable default (the free-text essentials) are still asked; guided — only the questions marked high-impact below, plus the free-text essentials; full — every question below. If the repo's CONVENTIONS.md records an Assessment depth:, pre-select it as the recommended option — the selector always appears (one narrow exception: when the invocation already answers every question the tiers differentiate, skip it and say so in one line); a recorded depth is never applied silently. Otherwise recommend full when the request arrived with little or no context and express when it is already fully specified. At any question the operator may answer "defaults from here" or "go deeper"; honour the switch immediately.

• Ask the questions below one at a time, each with a recommended option and a one-line reason; wait for each answer.

• Use structured selection (single- or multiple-choice). If the host exposes a structured single-/multi-select question tool, use it and mark the recommended option; otherwise list options A/B/C in plain text and name the recommended one. Use free text only where an enumerable set is impossible (e.g. the title).

• The operator decides. Never proceed past a question without an answer, and never guess scope when invoked with no context.

Questions (skip any the request already answers):

1. Shape — capability or technology (only if the repo splits shapes; single-shape repos skip this). Recommended: per the request's intent.
2. Supersede? — none, or select the ADR(s) this replaces. Recommended: none. (High-impact — asked in guided: supersession linkage is hard to reverse.)
3. Initial status — Proposed or Accepted. Recommended: Proposed. Reconstructing already-shipped work (a development built ahead of the process) is the exception: author at Implemented, Revision History citing the implementing commits and noting it was recorded after the fact, and write a matching plan/done entry.
4. Create a plan item now? — yes / no. Recommended: yes when Accepted.
5. Title — free text (the one unavoidable open answer; asked at every depth).

Step 1 — Determine shape and number

• Shape. If the repo uses a single ADR shape, use adr/0000-template.md. If it uses the split, decide capability vs. technology from the user's intent (what the system must do → capability; how it is built → technology); confirm with the user if ambiguous. Use adr/0000-template.md (capability) or the technology template (adr/NNNN-template.md).
• Number. Next contiguous integer after the highest existing ADR, zero-padded to 4 digits. No gaps, no reuse. For a split repo, keep capability ADRs below the cutoff and technology ADRs at/above it. In a federation (a federation.md exists), number contiguously within this repo — numbers are not unique across the federation. The ADR's federation identity is the recorded scheme applied to this number (default repo-prefixed slug <repo-id>/NNNN-slug).

Step 2 — Gather content

Ask for the pieces the chosen template needs, one prompt at a time:

• Title (sentence case), Context.
• Capability ADR: capability statement, user stories, numbered, testable acceptance criteria.
• Technology ADR: decision, rationale (name alternatives considered and give specific rejection reasons — reject "simpler"/"idiomatic" as insufficient), consequences, acceptance criteria.
• In an evidence-adopting repo (docflow.yml records evidence-adopted-at:): a Verify: method for each acceptance criterion — an inline command, gate-check, or manual (see CONVENTIONS.md §Verification Evidence). A criterion nobody can name a check for is not ready to be written — ask, don't invent. Avoid time-bound criteria: one whose truth is momentary ("the directory is empty", "no references exist yet") is permanently false on every future re-run at HEAD and becomes evidence debt the day it ships. Word criteria to be durably true, or scope them to the event they describe ("at adoption, …").
• If the repo keeps goals (a goals/ directory exists): offer serves: — which goal id(s) this record advances, as front matter. Every listed id must resolve to a goals/ file. Recommended: the goal the request names, or none.

Honour the language mandate if one is set.

Step 3 — Supersede / deprecate (only if replacing an ADR)

If this ADR replaces an existing one:

• Set supersedes: on the new ADR — intent only, at proposal. Do not touch the predecessor yet: supersession takes effect when the successor is Accepted (see Step 7). A merely-Proposed successor that is later withdrawn must leave the predecessor's standing decision untouched.
• Same-repo links use relative paths (adr/NNNN-*.md). In a federation, a link to an ADR in another repo uses the logical identity (<repo-id>/NNNN-slug), resolved via the member index along repo-id → Pointer → adr/NNNN-*.md — not a relative path.
• A pure deprecation (no successor) sets the target to Deprecated with a Revision History row — and is usually done directly, not via this skill.

Step 4 — Write

• Copy the chosen template, fill all placeholders. Status Proposed, today's date, owner = current agent/human.
• Seed the Revision History with an r1 — Initial draft row. Leave the Approvals table empty (it populates on Accepted).
• Do not invent acceptance criteria or rationale to fill space. If the user hasn't supplied enough to make a section meaningful, ask.

Step 5 — Wire up

• Regenerate INDEX.md from ADR metadata.
• If domains/ exists, add the ADR to the owning domain's README.md ADR list. If you assign the ADR to a domain that doesn't exist yet, offer to create domains/<slug>/README.md (at the recorded artefact root) and add the ADR to it — this enables the domains layer.
• Multi-agent mode 2: claim the file in _agent/LOCKS.md before editing, remove on commit. Mode 3: you are on a branch/worktree.

Step 6 — Commit

Conventional Commit, Rationale: footer (this touches an ADR). No Co-Authored-By trailer unless the repo's Git contract requires one.

Step 7 — Offer the next step

A new ADR is Proposed, not actionable yet. Offer to:

• Walk it to Accepted (populate Approvals, change status, regen INDEX) when the user is ready. If it supersedes an ADR, the flip happens here: on acceptance, set superseded-by: on the predecessor, advance it to Superseded, and append its Revision History row naming the successor.
• Create a plan/todo/ item for it (hand off to the new-plan skill). When the operator's acceptance in this flow already covered the item's exact scope, say so in the hand-off — the receiving skill treats those answers as given and does not re-ask them.
• If the operator turns the proposal down instead, set it Withdrawn (terminal), append the Revision History row with the reason, regen INDEX — never delete the file. Any supersedes: intent it carried simply lapses.