write-an-adr

name	write-an-adr
description	Write an Architectural Decision Record (ADR) to document a significant design choice. Use when user asks to write/create/document an ADR, or to record an architectural decision.

Write an Architectural Decision Record (ADR)

An ADR captures a single architecturally significant decision and its rationale. ADRs are stored in the adr/ directory at the repo root, numbered sequentially.

Background

This workflow follows the Nygard ADR format (Status, Context, Decision, Consequences) with practical additions (Date, Rationale, Considered Options) drawn from MADR and the project's existing conventions. See:

• Nygard's original post
• MADR
• adr.github.io

Prerequisites

• The user describes a decision that has been made (or is being proposed)
• If the user hasn't described the decision clearly, ask clarifying questions before writing

Steps

1. Determine the next ADR number:

   • List files in adr/ and find the highest existing number
   • Increment by 1, zero-padded to 4 digits (e.g., 0002)

2. Gather information from the user:

   • What problem or issue motivated this decision?
   • What was decided?
   • What alternatives were considered (if any)?
   • What are the expected consequences (positive, negative, neutral)?
   • What is the current status? (default: Proposed)
   • If the user has already provided this information (e.g., in a design doc, PR discussion, or prior conversation), extract it rather than asking again