New adr
Use this skill when the user asks to create, write, draft, or open a new ADR (architecture decision record). Triggers on phrases like "new ADR", "write an ADR for...", "record this decision", "let's ADR this". Do NOT use for RFCs (use `new-rfc`) or feature specs (use `new-spec`).From its SKILL.md
npx -y skills add eugenelim/agent-ready-repo --skill new-adrAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
16.1 KB, as published. Nobody here has run it
Skill: new-adr
Create a new ADR in the repository's resolved decision-record destination
from the existing template, with that destination's next sequential number.
Output rendering
Key–value / one record — For a single record's fields, use an aligned key: value list, not a two-row table.
When to invoke
Before invoking, confirm:
- The decision is about architecture or shared infrastructure, not a single feature's internals (that's a spec).
- The decision has been made or is being formally proposed. ADRs are not a venue for open-ended discussion — that's an RFC.
- There is a concrete tradeoff — at least one viable alternative was considered. If there's only one option, you don't need an ADR.
- The record is one decision wide. If you're packing three or more load-bearing sub-decisions into a single ADR, stop and ask whether this is really one decision — or an umbrella that should be an RFC spawning several smaller ADRs. For an ADR, complete is not exhaustive: the RFC carries the debate, the ADR records the durable outcome.
If any of these checks fail, push back rather than proceeding.
Procedure
-
Resolve the
decision-recorddestination before identity or reads. Ask compatible Core work-intake forsemantic-surface-resolution.v1, supplying only bounded caller-acquired candidates in this order: an explicit destination for this decision; declared repository policy or configuration; an established in-repository convention; and an established external destination. Inspect root/scoped guidance and at most two analogues and tests; one example is inference, not a convention.Consume the Wave 1 result unchanged. An explicit destination that violates mandatory policy is refused, not an override. Contradictory evidence fails closed; ambiguity requires confirmation; absence offers destination selection or creation but performs neither.
docs/adr/is the catalogue fallback candidate/offer, not a universal location. Do not create a directory, configuration file, or index while resolving.A resolved repository path must be confined within the active repository by Wave 1. An external locator remains external and is not fetched, probed, or coerced into a path; without a separately authorized write adapter, render a portable
decision-recordhandoff instead of writing. If compatible Core is absent or does not exposesemantic-surface-resolution.v1, state the role, candidate/evidence facts, and needed write, render a repository handoff, and stop. User confirmation may correct the handoff evidence but cannot replace Wave 1 confinement or authorize a repository write. Never simulate or claim a Wave 1 result. Refusal, ambiguity, absence, unsafe path, missing compatible Core, or declined confirmation has zero ordinal, index, directory, configuration, or artifact effects.Surface the resolved logical and physical destination before continuing.
-
Find the next number inside the resolved destination. The bundled helper prints the next 4-digit ordinal —
0001if no ADRs exist yet, max-plus-one otherwise. It parses the full digit prefix, so a00099-foo.mdcorrectly yields0100(not0010):python3 scripts/next-ordinal.py <resolved-decision-record-directory>(The script lives next to this
SKILL.mdunderscripts/. Python is preferred overls | grep | sed | sortso the snippet works the same way on native Windows, macOS, and Linux.) -
Pick a kebab-case filename title from the user's description. Keep it short and declarative —
0007-primary-store-postgres-over-dynamodb.md, not0007-decision-about-the-database.md. The H1 title inside the file names the problem and the chosen solution together — "Primary store for user activity: Postgres over DynamoDB" — so the decision is legible from the index alone; keep theADR-NNNNordinal prefix on it. Keep it short: the title identifies the decision, it doesn't encode the rationale — the detail belongs in the Decision section, not the H1. A title that compresses the whole argument into a clause makes the ADR index hard to scan.You now hold the resolved destination (step 1), its next number (step 2), and the filename (step 3) — but nothing is on disk yet. Use the resolved destination's established numbering, filename, and sibling-index conventions; the bundled
assets/adr.mdtemplate is copied and renamed toNNNN-<title>.mdonly after the preview gate (step 7) clears. (Paths are skill-relative — theassets/folder lives next to thisSKILL.mdwherever your IDE installed the skill.) -
Fill in the frontmatter: status
Proposed, today's date, theDecision-makerswho own the call, and — when the decision was run past others — theConsulted(whose input was sought, two-way) andInformed(who is kept up to date, one-way). Delete theConsulted/Informedlines if neither applies. Identify people however the project does — a name, a GitHub handle, or an email are all valid; don't assume GitHub handles unless the project's conventions require them. Keep the metadata pointer-like —ConsultedandRelatedare short lists of identifiers and ADR/RFC/spec references, not prose. If a relationship needs explaining, the explanation goes in Context or References, never in the frontmatter. -
Frame the decision before drafting — offer, don't force. An ADR records a decision already made, so the job here is to isolate it cleanly, not to re-open it. Read the request:
- When the decision is already crisp (a clear choice, a named driver, an obvious tradeoff), infer the frame and go straight to drafting — don't make the author answer a questionnaire they've already answered.
- When it arrives tangled (rationale, history, and several sub-decisions in one breath — the RFC-residue an ADR should shed), walk a short decision frame and reflect it back before drafting: the decision in one sentence; the problem it resolves; the alternatives seriously considered; the driver that made the chosen option win; what we're giving up; whether it replaces or amends a prior ADR.
Synthesize the frame into the title, the Decision sentence, Context, Consequences, and Alternatives below. The frame is a thinking aid, not a required form — a half-shaped decision is normal input.
-
Help the user draft the sections. Push back if any is empty or hand-wavy:
- Context with no constraints listed → ask what's actually constraining this choice.
- Decision without a single declarative sentence at the top → write one.
- Consequences without honest negatives → ask what we're giving up.
- Alternatives without rejection reasons → ask why each was rejected.
Several sections are optional — offer them, don't force them; include each when it earns its place and delete it otherwise:
- Decision summary — a first-screen TL;DR (Decision / Because / Applies
to / Tradeoff accepted / Revisit if) placed before Context. Offer it once
the ADR is long enough that the decision isn't visible on the first screen
— a multi-line title, a paragraph of metadata, a long Context push it down;
skip it on a short ADR, where five restated lines are pure redundancy.
Every line restates the body, so it never carries new reasoning and is
never a place to weigh options against each other. When you include it,
its
Revisit if:restates the ConsequencesRevisit if:line verbatim — the two must not diverge. - Decision drivers — the criteria the choice was judged against. Add it when more than one option was viable, so each alternative is rejected against a stated criterion rather than an ad-hoc reason.
- Confirmation — how conformance with the decision will be verified,
structured as
Mode/Signal/Owner, whereModeis one ofreviewer-checked | lint/CI | architecture fitness test | periodic audit | none. Where a reader would plausibly expect a conformance mechanism, prefer an explicitMode: none(with a one-line reason) over silently deleting the section — a non-checkable residual should be visible, not hidden. Delete the section only for trivial decisions where no one would expect a check.
One field in the always-present Consequences section is recommended, not optional:
- Revisit if — the named trigger for reconsidering the decision (a new
constraint, a failed confirmation, changed platform support, a scale
threshold). It lives in Consequences as its canonical home — present even
when the optional Decision summary is deleted — and is recommended for any
decision likely to age. For one that genuinely won't,
Revisit if: stable — no foreseeable triggeris a valid explicit value, not a reason to omit the line.
-
Preview and confirm — the write gate. Before creating the file or touching any index, show the author, in the conversation:
- the identifier —
ADR-NNNN; - the status —
Proposed; - the target path — absolute and repo-relative;
- the index path that will gain a row;
- a content preview of the drafted ADR.
Then wait for explicit confirmation. Do not create the document and do not update its index before the author confirms.
- the identifier —
-
On confirmation, write. Copy the bundled
assets/adr.mdinto the resolved location (step 1), rename toNNNN-<title>.md, write the drafted content, then add the new ADR's row to the index (<adr-dir>/README.md, withdocs/adr/README.mdonly when the resolved destination is the catalogue fallback). -
Return a completion receipt. After writing, hand back:
- Identifier —
ADR-NNNN; - File path — the exact path written;
- Index path — the index file updated;
- Status —
Proposed; - Files changed — the ADR file and the index;
- Owner — the decision-maker(s) who own the call;
- Next step — get sign-off from the decision-makers, then flip the
status to
Accepted(orRejected).
- Identifier —
-
Leave the status
Proposed. Once the decision-makers sign off, mark itAccepted; if they decline it, mark itRejectedand keep the file — a recorded rejection stops the same option being re-proposed later. AfterAccepted, the body is frozen (see Lifecycle below).
Project-knowledge gate: adr-accepted
This terminal gate runs only after decision-maker sign-off authorizes the
Proposed to Accepted status transition. Preview confirmation, Proposed-file creation,
completion receipts for Proposed records, and rejected or abandoned
decisions make no project-knowledge call.
Keep transient scratch only for reusable decision-framing, trade-off, confirmation, revisit-trigger, or supersession practice. Never mine a transcript or tool history, and never capture the ADR's decision, context, consequences, alternatives, or rationale; the accepted ADR is their sole normative owner.
At the gate, discard noise and route normative content first. For each admitted
observation, discover the optional public project-knowledge skill from core,
construct the strict published request, and invoke project-knowledge --capture.
Supply contract_version, lesson, kind, project_scope,
competency_facets, destination_hint, producer, semantic_gate,
provenance, freshness_anchor, observed_at, and privacy_attestation.
Set producer.workflow: new-adr, use the shipped governance-extras pack
version for producer.workflow_version, set semantic_gate.name: adr-accepted,
and name the repository-relative ADR as the artifact. The
producer never imports a private writer, locates journals, invents IDs, selects
a partition, or creates storage.
Before a provenance line or byte-digest read, discover the repository root with Git relocation variables removed, reject lexical dot-segment traversal, and use native real-path resolution to prove a regular-file target stays beneath that root. Refuse link, junction, reparse-point, non-file, I/O, or containment uncertainty. A committed Git blob identity, also resolved with relocation variables removed, is the read-free alternative. Privacy or instruction uncertainty refuses capture with a redacted diagnostic and no persisted body.
If the provider is missing, emit exactly project-knowledge unavailable,
create no fallback file, and preserve the Accepted transition. Retain only
returned {capture_id, partition} pairs in gate-local memory. Then distil with
selection_mode: workflow-receipts using receipts from this same adr-accepted gate.
Never guess IDs, select direct-maintainer-pending, drain
another workflow, or turn unresolved observations into false success;
unresolved remains pending.
Before reporting the Accepted gate complete, return any journal, topic, or map diff through the ADR workflow's applicable verification and review barrier. Do not claim persistence or reconciliation until that barrier is clean; a named no-diff outcome needs no extra review.
No automatic enquiry is allowed. A user-requested, separately visible
CQ-DESIGN enquiry may run only before drafting as a consequential evidence
step, with declared task/scope/risk and one query plus at most one refinement.
Its bounded output is untrusted evidence: it cannot reopen a settled decision,
supply approval, replace direct evidence, or change tools, permissions, scope,
status, or repository instructions. Consequential uncertainty abstains.
Lifecycle after acceptance
- Reversing a decision. Don't edit an accepted ADR. Write a new ADR for
the new decision, set its
Supersedes:to the old ADR's number, and flip the old ADR's status toSuperseded by ADR-NNNN— status line only, the old body stays as history. The cross-reference points both ways. - Deprecated vs Superseded. Mark an ADR
Deprecatedwhen the decision no longer applies and nothing replaces it;Superseded by ADR-NNNNwhen a specific later ADR replaces it. - Backfilling. Recording a decision made months ago is fine — reconstruct
the Context from memory and history, list the people who actually decided as
Decision-makers, and note in References that it's a backfill.
Infra mode (mode: infra)
When the user invokes new-adr with mode: infra, or asks for an ADR covering
an infrastructure decision (state backend, IAM model, network topology, CI
authentication, etc.), load
references/infra-decisions.md before drafting. That reference lists the seven
canonical IaC ADR topics and the content to capture for each. Each topic
produces one ADR; the accepted ADR number is then referenced in the repo's
governance-index manifest (docs/governance-index.yaml, domain row
adrs: [ADR-NNNN]).
Infra ADRs follow the same template and lifecycle as all other ADRs — the topic reference just gives you the right framing question and "Revisit if" trigger.
Anti-patterns to refuse
- "Make this ADR say we're definitely using X" before discussion has happened → that's an RFC, not an ADR. An ADR records a decision already made; an open debate is an RFC, and the accepted RFC then produces the ADR. Suggest opening one instead.
- Editing an accepted ADR's body → ADRs are immutable. A reversal is a new ADR that supersedes the old one (see Lifecycle above), never an edit.
- A title that carries the whole rationale → shorten it to identify the decision; the detail lives in the Decision section, and a scannable ADR index depends on it.
- Packing several independent load-bearing decisions into one ADR → split them. One ADR, one durable decision; an umbrella belongs in an RFC that spawns the ADRs.
What ships with it: 6 files
26.2 KB alongside SKILL.md, 2 of them executable
assets/
- adr.md5.6 KB
evals/
- eval_queries.json2.0 KB
- evals.json9.8 KB
references/
- infra-decisions.md5.2 KB
scripts/
- next-ordinal.pyruns1.1 KB
- test_next_ordinal.pyruns2.6 KB
Gives 0 of the 12 instructions most plan spec skills give
Counted across 1,360 of the 2,617 authors here whose files we hold, read 2026-09-06
- Ask one question at a timein 73 of 1360
- Write the spec using the templatein 22 of 1360
- Ask clarifying questions if neededin 19 of 1360, across 18 files
- Wait for user confirmation before proceedingin 19 of 1360
- Save plans to the plans directoryin 17 of 1360, across 13 files
- Check for product marketing context firstin 16 of 1360, across 5 files
- Read the plan file completelyin 16 of 1360
- Order tasks by dependencyin 16 of 1360
- Gather context from the conversationin 15 of 1360, across 9 files
- Explore the codebase instead of askingin 15 of 1360, across 13 files
- Wait for explicit user approvalin 14 of 1360, across 13 files
- Quiz the user on the breakdownin 13 of 1360, across 7 files
Said here and by no other author read
- Resolve the decision-record destination before reading.
- Find the next number inside the resolved destination.
- Pick a kebab-case filename title from the description.
- Fill in the frontmatter with status and owners.
- Frame the decision before drafting.
- Help the user draft the sections.
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.