Speq Adr Rules

ADR Rules

An ADR is a rare record of a durable decision. Most plans produce none. This skill is the single owner of the rules. Other skills and agents cite it and do not restate it.

1. Default No

• The expected number of Promotes to ADR: yes entries per plan is zero.
• Set yes only when a criterion in rule 2 applies and you can name it.
• Two or more yes entries in one plan get re-judged. Re-read each one against rule 2 and rule 3 before you keep it.
• A plan with many Design Decisions entries or many resolved review findings does not owe an ADR for each. Most decisions are local and stay no.

2. Criteria for Yes

A decision qualifies only when at least one of these holds:

• It affects multiple components.
• It sets a long-lived constraint that binds future work.
• It is a major technology, API, persistence, security, or deployment choice.
• It rejects a plausible alternative, and the reason will matter to a later reader.

The entry's Rationale names the criterion that applies and states the result of the search in rule 5.

3. Never an ADR

• Naming, file placement, and folder layout.
• A one-off bug fix.
• A scope trim or a task ordering choice.
• Implementation detail: function signatures, file paths, flags, data layout inside one module.
• A workaround specific to one plan's own mechanics, such as a spec-merge gap or a review-loop correction.
• A corollary of another decision. Record it as a bullet in the parent entry's Consequences line.
• A statement that already lives in a feature spec scenario.

4. Where It Goes Instead

An ADR records why. specs/architecture.md records what is.

To change an existing ADR, write a new ADR with Supersedes: <slug>. Do not edit the old fragment.

5. Search First

Before you set yes, read the ADR digest (/speq-cli) and any fragment that matches the decision. If an ADR already covers the decision, do not promote a duplicate. Either set no, or supersede that ADR when the decision has changed. State the search result in Rationale.

Every plan reads the accepted ADRs before it records design decisions. A plan whose decision, spec delta, or architecture delta contradicts an accepted ADR either conforms to it or supersedes it through a decision-log entry with Supersedes: <slug> and Promotes to ADR: yes. A silent contradiction is a defect.

6. One Decision, No Detail

• One ADR records one decision.
• Decision states the choice in plain words. It holds no function signatures, file paths, or flags.
• An ADR names a library but never pins its version. A version number lives in the manifest or lockfile. The Decision states the policy instead, for example "use the registry release, not a git tag".
• If the Decision needs a list of paths, signatures, or version numbers to make sense, the content is implementation detail. Move it to the plan.md task line, or to a decision-log.md ## Design Decisions entry with Promotes to ADR: no if it has a rejected alternative.

7. Shape

An ADR has four short sections: Context, Decision, Options Considered, Consequences.

• Options Considered appears only when a real alternative was rejected.
• Consequences appears only when the entry carries a Consequences line.
• Each section is a few sentences. A section that needs a page is more than one decision or holds implementation detail.

7a. Minimum Text, No History

An ADR holds the least text that states the decision. Follow /speq-writing-guardrails.

• State the current fact in the present tense. Do not narrate how the decision was reached: no earlier attempts, review rounds, plan names, dates, or "was changed from".
• Context is one or two sentences: the situation that forces the decision.
• Decision is one to three sentences.
• An Options Considered row is one line: the option and the reason it lost.
• Consequences are short bullets that name what becomes easier or harder.
• Do not copy a decision-log entry's Rationale or Alternatives prose into the ADR. Keep only what a later reader needs to understand why.
• Remove a sentence that a reader could drop without losing the decision or its reason.

8. Status Lifecycle

• An ADR is proposed at plan time. A Promotes to ADR: yes entry that passes rules 1 to 5 is the proposal. The plan skill prints it as an ADR candidate.
• Recording the plan is the acceptance. recorder-agent writes Status: Accepted when /speq-record runs.
• To reject a proposal, change the entry to Promotes to ADR: no and run the plan skill again before you record. In a PR run, comment on the draft PR and run /speq-plan-pr again with the PR number.
• Deprecated and Superseded by <slug> follow the existing rules.

9. Vocabulary