Help us improve
Share bugs, ideas, or general feedback.
From sdd
Records a post-hoc or asynchronous architecture decision as a MADR ADR when the decision was not captured during the synchronous design pass. Confirms worthiness, numbers the ADR, fills context/drivers/options/outcome/consequences, and supports a Proposed→Accepted review flow.
npx claudepluginhub genkovich/sdd --plugin sddHow this skill is triggered — by the user, by Claude, or both
Slash command
/sdd:decide-adropusThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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 ...
Records concise Architecture Decision Records (ADRs) capturing what was decided and why, for decisions that are hard to reverse, surprising without context, or involve real trade-offs.
Generates standardized Architecture Decision Records (ADRs) documenting technical decisions, context, evaluated alternatives, rationale, and consequences. Saves sequentially to docs/adr/.
Records architectural decisions as ADRs from design documents. Use after brainstorming or planning to capture what was decided, why, and alternatives considered.
Share bugs, ideas, or general feedback.
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 · ../design/references/blast-radius.md
Decision author (usually the Architect or Tech Lead). A reviewer (Tech Lead, plus Security when relevant) signs off the Proposed → Accepted transition.
<slug> — the feature slug, same as every earlier stage.<title> — kebab-case, describes the decision, not the problem (time-sortable-ids, not id-strategy).sad.md §4 Solution strategy / §9 ADR index / §11 Risks, or supplied by the user.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.test -d docs/features/<slug>. Missing → ask whether to proceed standalone (AskUserQuestion, phrasing per ../_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.../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.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).NNNN = (count of existing adr/*.md) + 1, zero-padded to 4 digits (0001, 0002, …). Never reuse a number.../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.sad.md is absent — an explicit note that there is no design document, so the context is reconstructed from the author.<!-- TBD --> only where a number honestly needs a spike.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.sad.md §9 ADR index (and link from tasks/_epic.md if the ADR scopes a specific task). The ADR's own ## Links must point up to the spec + the relevant sad.md §N — no orphans.adr: <slug> NNNN <title>. Then emit the stage-handoff block per ../_shared/handoff.md (utility variant) — What I did + Review (adr/NNNN-<title>.md) + Run next: resume the gate that needed it (/sdd:tasks <slug> or /sdd:plan-tests <slug>); /clear optional.docs/features/<slug>/adr/NNNN-<title>.md exists in design's MADR format (frontmatter + Context + Decision drivers + Considered options + Decision outcome + Consequences + Links).NNNN is correct (existing count + 1, 4-digit) and the title is in decision-form (0007-time-sortable-ids.md ✓ vs 0007-id-strategy.md ✗).status is explicit — Accepted (final) or Proposed (reviewer pending, reviewers filled).sad.md §9 (when sad.md exists) and the ADR's ## Links point up to spec + sad §N. A genuinely standalone ADR notes the missing design context instead.Superseded by NNNN, never silently duplicated.design (spawned inline, Accepted); decide-adr is for what missed that pass.spec.md / data-model / api.0007-id-strategy.md) — in the §9 index it's unclear which decision exists. Use the decision (0007-time-sortable-ids.md).../design/templates/adr.md; a second ADR format fragments the genre.## Links up to spec/sad — six-month archaeology can't find it.../design/templates/adr.md — the canonical MADR scaffold this skill copies and fills (owned by design; do not duplicate it here).../design/references/blast-radius.md — the 3-criteria worthiness gate (irreversible / multi-module / legitimate alternatives); same gate design runs, applied here to confirm the decision earns an ADR.../_shared/ask-style.md — phrasing for the standalone-confirm, worthiness-borderline, and Superseded questions.User: «ADR for time-sortable-ids on checkout-discounts —
tasksflagged a missing ADR for the id-generation choice» Skill:docs/features/checkout-discounts/exists withsad.md→ reads §4/§9/§11. Blast-radius: id strategy is irreversible (a switch later needs a backfill across every row) + multi-module (other modules read the ids) → 2-of-3, proceed.ls adr/→0001,0002exist →NNNN = 0003. Title0003-time-sortable-ids.md(decision-form). Copies../design/templates/adr.md. Context: the §11 risk on hot-row contention forced an explicit id choice. Drivers: spec §6 NFR (predictable ordering) + the existing capability in the stack. Options: (a) time-sortable ids generated in the app; (b) database auto-increment; (c) random ids. Outcome: «Chosen: (a)» — keeps natural ordering without a central sequence; (b) couples to one writer, (c) loses ordering. Consequences: + ordered without coordination; − slightly larger ids than auto-increment; neutral: switching later needs a backfill. StatusAccepted. Adds a §9 row, fills## Links. Commitadr: checkout-discounts 0003 time-sortable-ids.