architecture-decision-record

Overview

Generates Architecture Decision Records from design conversations, meeting notes, or direct prompts. Walks through decision drivers, options considered, and consequences, then produces a numbered, versioned markdown file ready for commit to a docs repository.

Workflow

<Definition - ADR Status> Each ADR carries exactly one status at any time:

• Proposed: Decision documented but not yet ratified by the team.
• Accepted: Decision ratified and in effect.
• Deprecated: Decision no longer applies due to changed circumstances but remains in the record for history.
• Superseded: Decision replaced by a newer ADR. The superseded record links forward to its replacement, and the replacement links back. </Definition - ADR Status>

<Definition - MADR Format> Markdown Any Decision Record (MADR) is a lean, structured template popularized by the adr-tools community. Sections: Title, Status, Context and Problem Statement, Decision Drivers, Considered Options, Decision Outcome (with Rationale), Consequences (Positive, Negative, Neutral), and optional Links to related ADRs. </Definition - MADR Format>

<Definition - Nygard Format> Michael Nygard's original ADR format. Sections: Title, Status, Context, Decision, Consequences. Shorter and less prescriptive than MADR. Best for teams that prefer brevity over exhaustive structure. </Definition - Nygard Format>

<Definition - ADR Numbering> ADRs are numbered sequentially with zero-padded four-digit prefixes (e.g., 0001, 0002). The number is determined by scanning the target directory for existing ADR files and incrementing the highest found number by one. If no directory is specified or no existing ADRs are found, numbering starts at 0001. </Definition - ADR Numbering>

<Workflow - Generate ADR description="End-to-end ADR generation from input to written file." tools=[file_write, file_read, run_python, open_in_session_tab] triggers=["create an ADR", "document this architecture decision", "record why we chose X", "write a decision record", "ADR for this design choice"]

1. [Ask user] Gather the decision title if not already provided. Confirm the template choice (madr, nygard, or custom). If context was supplied (transcript, notes, or description), acknowledge it. If no context was given, ask the user to describe the decision background in a few sentences. If fails: If the decision title or template choice is missing, re-ask the user for the missing item before continuing.
2. [Decide] If the user selected "custom" template, ask them to describe or paste their preferred format. Store the structure for use in the drafting step. Otherwise, proceed with the selected standard template.
3. [Think] Analyze the provided context. Extract: the core problem or question, factors that drove the decision (performance, cost, team expertise, timeline), distinct options that were discussed, the chosen option, and any stated trade-offs or risks. If the context is a long transcript, identify only the segments relevant to this specific decision.

4. [Ask user] Present the extracted elements in a structured summary:

   • Problem Statement: (one or two sentences)
   • Decision Drivers: (bulleted list)
   • Options Considered: (numbered list with one-line descriptions)
   • Chosen Option: (name)
   • Key Rationale: (why this over the others)

   Ask the user to confirm, correct, or add missing items. Per Rule 1, if options are unclear, explicitly ask "Were there other alternatives discussed?" If fails: If the user does not confirm or correct the elements, re-present the summary and ask specifically which items to add or fix.

5. [Ask user] Ask about consequences. Per Rule 6, prompt the user: "What positive outcomes do you expect from this decision? What are the downsides or risks?" If the user provides at least one of each, proceed. If not, suggest plausible consequences based on the context and ask for confirmation. If fails: If no consequences are provided or confirmed, propose at least one positive and one negative consequence from the context and ask the user to confirm.
6. [Ask user] Confirm the status for this ADR. Default is "Proposed." Ask: "Is this decision already accepted by the team, or should it remain as Proposed for review?" If fails: If the user does not specify a status, default to Proposed and note that the status can be updated later.
7. [Ask user] Ask where the ADR file should be saved. Offer to scan the workspace for existing ADR directories. If the user names a path, use it directly. If fails: If no save location is given, offer to scan the workspace for ADR directories and ask the user to pick one.
8. [Agent] Scan the target directory for existing ADR files matching the pattern NNNN-*.md. Determine the next sequential number. If the directory does not exist, create it and start at 0001. If fails: If the directory cannot be scanned or created, report the path error to the user and ask for a valid location.
9. [Decide] Does this ADR supersede an existing one? If the user indicated it replaces a prior decision, identify the old ADR file. Read its current status. Prepare to update the old file's status to "Superseded" with a forward link per Rule 7.
10. [Think] Compose the full ADR document using the selected template. Populate every section with user-confirmed content. Use the appropriate template from the Templates block below. Ensure the file name follows Rule 8.
11. [Ask user] Present the complete draft ADR in a code block. Ask: "Does this look correct? Any changes before I write the file?" Wait for explicit approval. Validate: User approves or requests edits. If edits requested, incorporate and re-present. If fails: If the user does not approve or request edits, re-present the draft and ask for explicit approval before writing.
12. [Agent] Write the ADR file to the target directory with the computed file name. If this ADR supersedes another, update the old file's status line and append the "Superseded by" link. If fails: If the ADR file cannot be written, report the write error, retry once, and present the draft inline if the retry fails.
13. [Agent] Open the newly created ADR in the session tab for the user to review in rendered markdown. If fails: If the ADR cannot be opened in the session tab, report the error and provide the file path so the user can open it manually.
14. [Agent] Present a summary: file path, ADR number, status, and a reminder to check for numbering collisions before merging (per Gotchas). If fails: If the summary cannot be presented, report the error and restate the file path and ADR number directly.

</Workflow - Generate ADR>

<Template - MADR>

# {{number}}. {{decision_title}}

Date: {{date}}

## Status

{{status}}

## Context and Problem Statement

{{context_and_problem}}

## Decision Drivers

{{decision_drivers_bulleted}}

## Considered Options

{{options_numbered}}

## Decision Outcome

Chosen option: "{{chosen_option}}", because {{rationale}}.

### Positive Consequences

{{positive_consequences_bulleted}}

### Negative Consequences

{{negative_consequences_bulleted}}

## Links

{{links_to_related_adrs}}

</Template - MADR>

<Template - Nygard>

# {{number}}. {{decision_title}}

Date: {{date}}

## Status

{{status}}

## Context

{{context_paragraph}}

## Decision

{{decision_paragraph}}

## Consequences

{{consequences_paragraph}}

</Template - Nygard>