Spec Loop Write Adr

Use this skill for ADR writing only.

Before doing that work, read adr-format.md and apply it.

Read and apply project instructions such as AGENTS.md when present.

This skill writes ADRs. It does not decide whether an ADR is required. Routing belongs to spec-loop-plan-task/SKILL.md.

The ADR being drafted or updated is the governing artifact for this skill.

Use the same ADR format whether or not a task artifact also exists.

Mandatory clarification gate

Before drafting or revising the ADR as current truth, check whether any important open decision remains about the decision, its criteria, trade-offs, credible options, or the boundaries of the decision.

If yes, create only enough ADR structure to hold the topic and current evidence safely, then use spec-loop-clarify-task/SKILL.md before continuing. Do not wait for the user to ask for clarification explicitly.

Re-run this gate whenever later ADR drafting exposes a new important open decision.

Before writing or revising, classify each input item into its proper section:

• Context = pre-decision facts that would still be true under

another credible alternative, such as requirements, constraints, current-state findings, scope boundaries, and explicit deferrals;

• Alternatives = credible competing options;
• Analysis = the clarified reasoning, accepted criteria,

trade-offs, option comparisons, and brief reasons the chosen option won; and

• Decision = the chosen outcome as a concise TL;DR, including any

explicit deferrals or major retained boundaries that are part of the outcome.

Treat Analysis as the ADR's authoritative decision-and-reason ledger. Do not repeat an Analysis point elsewhere in decision-and-reason form.

When a task artifact exists, use its Research, Analysis, and other ADR-relevant sections such as Constraints, Design, and, when relevant, Scenario as the primary ADR inputs. Otherwise use confirmed chat clarification and other current evidence.

ADR format

Store ADR files under architecture-decisions/, one file per decision.

ADR file names must use readable descriptive words, without prefixes, numbering, or abbreviations.

Use this exact top-level section order:

• Title:
• Date:
• Status:
• Decision:
• Context:
• Alternatives:
• Analysis:

Use plain label lines with colon suffixes, as in existing ADR files.

Section meaning

Title

Short decision topic.

Date

ADR date in YYYY-MM-DD format.

Status

Use the project's status words when they exist. Otherwise use plain statuses such as Proposed, Accepted, or Superseded.

Decision

Put the chosen outcome first.

Keep it short, direct, and reviewable. The reader should understand the answer without reading the rest of the document.

Include explicit deferrals or major retained boundaries here when they are part of the chosen outcome.

Context

Record only pre-decision facts: background, constraints, current-state findings, scope boundaries, explicit deferrals, and other conditions that were already true before the choice.

A Context item must still be true if another credible alternative had been chosen.

When a task artifact exists, draw this section mainly from its Research section.

Do not put accepted option choices, ranking outcomes, clarified preference statements, or decision rationale here.

Alternatives

Record the credible competing options.

Use a compact numbered list when more than one alternative matters. Keep weak or obviously non-credible options out.

When there is only one meaningful non-chosen alternative, record it briefly rather than inflating the section.

Analysis

Record the accepted decision criteria, accepted clarification decisions, and brief reasons that support the chosen decision.

Use a compact bullet list, not a prose paragraph.

Keep only the ADR-relevant subset here.

When a task artifact exists, draw this section from the ADR-relevant subset of its Analysis section. Do not copy the whole task ledger.

Analysis is the ADR's authoritative decision-and-reason ledger. Do not repeat its points elsewhere in decision-and-reason form. Do not duplicate the full alternatives here. Do not put open questions, confidence values, transient notes, chain-of-thought, chat history, or step-by-step internal reasoning here.

Update and supersede rules

• Update an ADR in place when the decision is still the same and the

change only clarifies, corrects, or completes that ADR.

• Create a new ADR when the architectural decision is materially new

or when an accepted ADR is being replaced.

• When one ADR supersedes another, mark the older ADR as

Superseded and mention the replacement in nearby prose.