/decide-adr

name: decide-adr
model: inherit
effort: high
agents: []
description: >
  Use to record a post-hoc or asynchronous architecture decision as a MADR ADR when it
  was NOT captured during the synchronous design pass — a choice made in code, in a chat,
  on a whiteboard, or one a tasks/review gate flagged as missing. Triggers on "ADR for
  {decision}", "adr for {slug}", "document the decision on {topic}", "lock in the decision
  about {X}", "MADR for {topic}", "/sdd:decide-adr {slug} {title}", "створи ADR для рішення",
  "задокументуй рішення", "ADR на {тему}". Confirms the decision is ADR-worthy via the
  blast-radius gate, picks the next 4-digit number, copies design's MADR template, and
  fills context / drivers / considered options / outcome / honest consequences. Supports a
  Proposed → Accepted review flow. Output: docs/features/{slug}/adr/NNNN-{title}.md.
  For decisions made live with the user, use `design` — it spawns ADRs inline (Accepted).

Skill: decide-adr

The **post-hoc / asynchronous ADR path** (pipeline stage 8a). `design` spawns ADRs synchronously and `Accepted` while you walk it Socratically; `decide-adr` records a decision that *missed* that pass — already in code, agreed in a chat, sketched on a whiteboard, or flagged by a `tasks`/review gate as a contract with no ADR behind it. It can also run a `Proposed → Accepted` review flow when the decision still needs a reviewer's sign-off. One file = one decision; it reuses design's MADR template, so there is **no second ADR format here**.

It is a recording utility, not a Socratic design stage — it does **not** run the shared Socratic loop or critic. The two shared dependencies are question phrasing and the worthiness gate: → [`../_shared/ask-style.md`](../_shared/ask-style.md) · [`../design/references/blast-radius.md`](../design/references/blast-radius.md)

ADR prose (context / drivers / consequences) follows `artifact_language` — the MADR headings and `Status:` values (`Proposed` / `Accepted` / …) stay English → [`../_shared/artifact-language.md`](../_shared/artifact-language.md).

Owner

Decision author (usually the Architect or Tech Lead). A reviewer (Tech Lead, plus Security when relevant) signs off the `Proposed → Accepted` transition.

Inputs

• `<slug>` — the feature slug, same as every earlier stage.
• `<title>` — kebab-case, describes the **decision**, not the problem (`time-sortable-ids`, not `id-strategy`).
• The decision itself + its alternatives — pulled from `sad.md` §4 Solution strategy / §9 ADR index / §11 Risks, or supplied by the user.
• **Input gate (soft).** Expects `docs/features/<slug>/` to exist, ideally with `sad.md` (decide-adr reads its §4/§9/§11 for context and drivers). If the decision is genuinely standalone — no feature folder yet — allow it, but **note the missing design context** in the ADR's Context section and warn the user, rather than refusing.

Protocol

1. **Locate the feature.** `test -d docs/features/<slug>`. Missing → ask whether to proceed standalone (`AskUserQuestion`, phrasing per [`../_shared/ask-style.md`](../_shared/ask-style.md)). On «yes», create `docs/features/<slug>/adr/` and flag that design context is absent. `sad.md` present → read its §4 (strategy), §9 (existing ADR index), §11 (risks); absent → note it and source context from the user. 2. **Worthiness check.** Score the decision against the **blast-radius gate** — [`../design/references/blast-radius.md`](../design/references/blast-radius.md) (irreversible / multi-module / has legitimate alternatives). 2-of-3 → proceed. Below the bar → tell the user it's likely inline-in-`sad.md` material, not an ADR, and confirm before writing one anyway. 3. **Dedup.** `ls docs/features/<slug>/adr/*.md 2>/dev/null`. An Accepted ADR on the same topic exists → don't duplicate: propose either editing it or a new ADR that marks the old one `Superseded by NNNN` (and stamps the old one's `status` + `updated_at`). 4. **Pick the number.** `NNNN` = (count of existing `adr/*.md`) + 1, zero-padded to 4 digits (`0001`, `0002`, …). Never reuse a number. 5. **Copy the template.** Copy [`../design/templates/adr.md`](../design/templates/adr.md) → `docs/features/<slug>/adr/NNNN-<title>.md`. This is the canonical MADR shape, owned by `design` and referenced here — do not invent a variant. Patch frontmatter: `owner`, `updated_at: <today>`, `feature_size` (from `.size` if present), `ticket`. Steps 6–11 each write their section into this file as soon as it's settled — progressive writes per [`../_shared/write-and-commit.md`](../_shared/write-and-commit.md). 6. **Context.** 2–4 sentences: what forced this decision (an NFR, an incident, a constraint), and — if `sad.md` is absent — an explicit note that there is no design document, so the context is reconstructed from the author. 7. **Decision drivers.** Bullets — the quality goals / constraints that pushed the choice, each traceable to a real source (spec §6 NFR, sad.md §2 Constraints, a §1 top-3 quality goal). Don't invent drivers; they filter out pet decisions. 8. **Considered options.** List **all** serious options (≥2 — one option is a declaration, not a decision), one line each with its trade-off. No strawman (an option an existing constraint already rules out). 9. **Decision outcome.** «Chosen: <option>» + 1–2 sentences on why it won, citing the drivers above. 10. **Consequences.** Positive **and** Negative **and** Neutral — cons included, or it's rationalisation, not a record. Name what changes in the codebase, ops, monitoring, onboarding. `<!-- TBD -->` only where a number honestly needs a spike. 11. **Status.** `Proposed` while a reviewer still has to sign off; `Accepted` once final. Run the review flow when needed: write `Proposed`, fill `reviewers`, and on sign-off flip to `Accepted` and bump `updated_at`. A reader six months on must be able to tell a live plan from a settled fact. 12. **Close the loop.** Add a row to `sad.md` §9 ADR index (and link from `tasks/_epic.md` if the ADR