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
| Content |
Destination |
| Conventions that bind contributors or agents |
CLAUDE.md, AGENTS.md, a .speq/*-hook.md file, or specs/mission.md Constraints |
| WHAT the system is: components and boundaries |
specs/architecture.md, changed through an architecture delta |
| HOW this plan builds it |
A phrase in the plan.md task line. Only a choice with a rejected alternative gets a decision-log.md ## Design Decisions entry with Promotes to ADR: no |
| Execution steps |
plan.md ## Implementation Tasks |
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.
/speq-patch writes an ADR with Status: Accepted into its own fragment. Committing the patch is the acceptance. Under /speq-patch-pr, merging the patch PR is the acceptance, and a reviewer rejects the ADR by asking on the PR for the fragment's removal.
Deprecated and Superseded by <slug> follow the existing rules.
9. Vocabulary
| Term |
Meaning |
| ADR |
A permanent record in specs/_decision/ of one durable decision |
| Plan context |
The ## Context part of plan.md: a bullet list of the problem and the forces behind one plan's change. It holds no decisions and is not an ADR |
| Decision-log entry |
A note in a plan's decision-log.md. Only an entry marked Promotes to ADR: yes can become an ADR |
| ADR candidate |
A decision-log entry marked Promotes to ADR: yes. It is the proposal, shown when the plan is ready |
| Accepted |
An ADR written by /speq-record or /speq-patch. Recording the plan, committing the patch, or merging the patch PR is the acceptance |
1---2name: speq-adr-rules3description: "When a decision becomes an ADR: the default is no, only durable decisions qualify, search first, one decision per ADR. Use inside a /speq-plan, /speq-record, /speq-patch, or /speq-audit run."4metadata:5 source: https://skillmd.com/skills/exasol-labs/speq-adr-rules6---78# ADR Rules910An 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.1112## 1. Default No1314- The expected number of `Promotes to ADR: yes` entries per plan is zero.15- Set `yes` only when a criterion in rule 2 applies and you can name it.16- 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.17- 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`.1819## 2. Criteria for Yes2021A decision qualifies only when at least one of these holds:2223- It affects multiple components.24- It sets a long-lived constraint that binds future work.25- It is a major technology, API, persistence, security, or deployment choice.26- It rejects a plausible alternative, and the reason will matter to a later reader.2728The entry's Rationale names the criterion that applies and states the result of the search in rule 5.2930## 3. Never an ADR3132- Naming, file placement, and folder layout.33- A one-off bug fix.34- A scope trim or a task ordering choice.35- Implementation detail: function signatures, file paths, flags, data layout inside one module.36- A workaround specific to one plan's own mechanics, such as a spec-merge gap or a review-loop correction.37- A corollary of another decision. Record it as a bullet in the parent entry's Consequences line.38- A statement that already lives in a feature spec scenario.3940## 4. Where It Goes Instead4142| Content | Destination |43|---------|-------------|44| Conventions that bind contributors or agents | `CLAUDE.md`, `AGENTS.md`, a `.speq/*-hook.md` file, or `specs/mission.md` Constraints |45| WHAT the system is: components and boundaries | `specs/architecture.md`, changed through an architecture delta |46| HOW this plan builds it | A phrase in the `plan.md` task line. Only a choice with a rejected alternative gets a `decision-log.md` `## Design Decisions` entry with `Promotes to ADR: no` |47| Execution steps | `plan.md` `## Implementation Tasks` |4849An ADR records why. specs/architecture.md records what is.5051To change an existing ADR, write a new ADR with `Supersedes: <slug>`. Do not edit the old fragment.5253## 5. Search First5455Before 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.5657Every 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.5859## 6. One Decision, No Detail6061- One ADR records one decision.62- Decision states the choice in plain words. It holds no function signatures, file paths, or flags.63- 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".64- 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.6566## 7. Shape6768An ADR has four short sections: Context, Decision, Options Considered, Consequences.6970- Options Considered appears only when a real alternative was rejected.71- Consequences appears only when the entry carries a Consequences line.72- Each section is a few sentences. A section that needs a page is more than one decision or holds implementation detail.7374## 7a. Minimum Text, No History7576An ADR holds the least text that states the decision. Follow `/speq-writing-guardrails`.7778- 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".79- Context is one or two sentences: the situation that forces the decision.80- Decision is one to three sentences.81- An Options Considered row is one line: the option and the reason it lost.82- Consequences are short bullets that name what becomes easier or harder.83- 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.84- Remove a sentence that a reader could drop without losing the decision or its reason.8586## 8. Status Lifecycle8788- 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.89- Recording the plan is the acceptance. `recorder-agent` writes `Status: Accepted` when `/speq-record` runs.90- 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.91- `/speq-patch` writes an ADR with `Status: Accepted` into its own fragment. Committing the patch is the acceptance. Under `/speq-patch-pr`, merging the patch PR is the acceptance, and a reviewer rejects the ADR by asking on the PR for the fragment's removal.92- `Deprecated` and `Superseded by <slug>` follow the existing rules.9394## 9. Vocabulary9596| Term | Meaning |97|------|---------|98| ADR | A permanent record in `specs/_decision/` of one durable decision |99| Plan context | The `## Context` part of `plan.md`: a bullet list of the problem and the forces behind one plan's change. It holds no decisions and is not an ADR |100| Decision-log entry | A note in a plan's `decision-log.md`. Only an entry marked `Promotes to ADR: yes` can become an ADR |101| ADR candidate | A decision-log entry marked `Promotes to ADR: yes`. It is the proposal, shown when the plan is ready |102| Accepted | An ADR written by `/speq-record` or `/speq-patch`. Recording the plan, committing the patch, or merging the patch PR is the acceptance |