Architecture Decisions
When to use
- Record a decision only when all three hold: it is hard to reverse, it would be surprising without the reasons behind it, and there were genuine trade-offs between real options. A datastore, a sync/async boundary, a framework, a public contract, or a security model is such a decision.
- Skip when any of the three is missing. A reversible, obvious, or inevitable choice is noise as an ADR; return the skip to the invoking skill.
Step 1: Draft the ADR
Open assets/adr-template.md before Step 1's actions; it owns the fields,
so fill every one. Read references/adr-example.md when the first draft is
written and needs comparing against a filled example.
- State the question and the artifact or system the decision covers.
- Weigh at least two real options. For each, record what it assumes, where it breaks, what would rule it out, what reversing it would cost, and the evidence. Wherever keeping things as they are, or deferring the decision, is viable, weigh that too; where it is not, record the evidence that says so.
- Give every assumption a stable ID and a way to be proved wrong.
- Keep every rejected alternative; never edit one away.
Step 2: Persist, then challenge
Append the ADR, with status
proposed, to.sdlc-skills/designs/{{YYYY-MM-DD}}-{{topic}}.mdor the user-set path, keeping what is already in the file. The ADR is immutable: never edit it after this. Compute its identity now, by the rule the template names (the artifact layout's section rule inusing-sdlc-skills: the first 7 characters ofgit hash-objectover the ADR's own section); the challenge binds to this path and this identity.If the choice is irreversible (its
Consequences and reversalfield says undo is impossible or unaffordable, not merely costly) and a dispatch action exists, fillassets/adr-challenger.mdwith that path and identity before dispatching it. Dispatch it asdispatching-parallel-agentsStep 2 says, to a reviewer other than the sole author. That reviewer challenges the options, the assumptions, the consequences, and the reversal under the template's challenge contract.Otherwise, write the strongest counter-case yourself, against that same contract, and label it self-challenge. When the dispatch action is not callable, write it only if the user chooses option 1 at the
dispatching-parallel-agentsStep 2 question. A self-challenge never issues the verdictclear, so the risk it leaves open goes to the decision owner in Step 3.Approval waits for
clearon this ADR identity, or for the decision owner accepting a labelled self-challenge.revisetakes one successor ADR and one re-challenge;inconclusive, the missing input and one rerun. If still notclear, report the open findings to the decision owner and end the turn. The owner accepts a finding only by naming it: recordaccepted by {{owner}}with the finding in the ledger, and present Step 3 once every open finding is accepted or corrected. A reply that names none accepts none. Skip both the dispatched challenge and the self-challenge only when a current independent design review covers this exact ADR identity.
Step 3: Present and track
Present:
ADR {{identity (per template)}}: {{question}} Proposed: {{choice}} — {{rationale, one line}} Rejected: {{alternatives}} Reversal cost: {{one line}} Challenge: {{clear | self-challenge | design review}} — {{open risk, or none}} 1. Accept 2. Reject in favor of {{other option}} 3. Request changes 4. Cancel Recommendation: {{option the recorded trade-offs support}} — {{one sentence}}.Ask this and end the turn;
clarifying-intentowns what closes it.Track the decision and its conformance (evidence that the accepted choice is implemented, as the ADR's conformance contract requires) as two separate things. Acceptance puts nothing
in force; conformance does. Retirement needs an action by the owner and the absence of the surface the ADR governs. If code or a later decision contradicts an accepted ADR, add a row to its lifecycle ledger and tell the owners itsDownstream impactnames.Return the recorded outcome to the skill that invoked this one.
Gotchas
- An assumption's "way to be proved wrong" (Step 1) can succeed after the ADR is accepted. The ADR itself is immutable and append-only (Step 2), so a disproven assumption is never fixed by editing the original. It needs a new ADR that supersedes the old one, the same way a rejected alternative is kept rather than removed.
- Step 2's reviewer-skip condition requires a current review of this exact ADR identity. A design review that covered an earlier draft, before an option was reweighed or an assumption added, no longer satisfies either word, even though it can feel like "we already reviewed this."
Common mistakes
- Treating "the code now does this" as owner approval or conformance proof.