Create Adr

---
name: create-adr
description: Interactively create an architecture decision record (ADR). Use
  when the user wants to document an architectural decision, technology choice,
  or significant design decision. Guides through context gathering, options
  analysis, and consequence documentation.
argument-hint: "[topic or description] [--supersedes ADR-NNNN]"
allowed-tools:
  - Bash(accelerator config *)
  - Bash(accelerator corpus adr *)
  - Bash(accelerator corpus metadata derive)
  - Bash(accelerator corpus frontmatter validate *)
---

# Create Architecture Decision Record

!`accelerator config context --skill create-adr --fail-safe`
!`accelerator config agents --fail-safe`

If no "Agent Names" section appears above, use these defaults:
accelerator:reviewer, accelerator:codebase-locator,
accelerator:codebase-analyser, accelerator:codebase-pattern-finder,
accelerator:documents-locator, accelerator:documents-analyser,
accelerator:web-search-researcher.

**Decisions directory**: !`accelerator config path decisions --fail-safe`

You are tasked with guiding the user through creating an architecture decision
record (ADR) — a concise document capturing a significant architectural
decision, its context, the options considered, and the consequences.

## Initial Setup

When this command is invoked:

1. **Check if parameters were provided**:

- If a topic/description was provided, proceed directly to context gathering
- If `--supersedes ADR-NNNN` was provided, note the supersession target
- If no parameters provided, respond with:

```
I'll help you create an architecture decision record. Please provide:
1. The topic or decision to document (e.g., "use PostgreSQL for user data")
2. Any relevant context or constraints

You can also specify if this supersedes an existing ADR:
`/accelerator:create-adr use Redis for caching --supersedes ADR-0003`
```

Then wait for the user's input.

## Process Steps

### Step 1: Determine ADR Number

1. Run the corpus CLI to get the next ADR number:

   ```
   accelerator corpus adr next-number
   ```

2. If `--supersedes ADR-NNNN` was specified:
   - Find the target ADR file by matching `{decisions directory}/ADR-NNNN-*.md`
   - Verify exactly one file matches the glob pattern (error if zero or
     multiple matches)
   - Read the target ADR's status using the corpus CLI:
     ```
     accelerator corpus adr read-status <resolved-path>
     ```
   - Verify the target ADR is in `accepted` status (only accepted ADRs can be
     superseded). This is an early-fail check to avoid wasted effort — the
     status will be re-verified before writing in Step 4.
   - If not `accepted`, inform the user and ask how to proceed

### Step 2: Gather Context

1. **Spawn agents to gather relevant context** (in parallel):

- Use **{documents locator agent}** to find related research, plans, and existing ADRs
  in the configured document directories
- Use **{codebase locator agent}** to find relevant code related to the decision topic

2. **Read any directly mentioned files** fully

3. **Present gathered context and ask clarifying questions**:

```
Based on my research, here's what I found relevant to this decision:

**Related documents:**
- [list of relevant meta documents]

**Related code:**
- [list of relevant code areas]

**Existing ADRs on related topics:**
- [list of related ADRs, if any]

Before I draft the ADR, I'd like to understand:
1. What forces or constraints are driving this decision?
2. What alternatives have you considered?
3. Are there specific tradeoffs you want to highlight?
```

If context gathering finds nothing relevant (e.g., first ADR in a new project),
skip the context sections and present:

```
No existing documents or ADRs found related to this topic. I'll draft the ADR
based on the information you provide.

Before I draft, I'd like to understand:
1. What forces or constraints are driving this decision?
2. What alternatives have you considered?
3. Are there specific tradeoffs you want to highlight?
```

Wait for user input before proceeding.

### Step 3: Draft the ADR

1. **Gather metadata** by running
   `accelerator corpus metadata derive`.

2. **Draft the ADR** using the template below and present it to the user for
   review:

```
Here's my draft ADR:

[draft content]
```

Use the `AskUserQuestion` tool with two options:

1. **Yes, write to disk** — save the ADR as shown
2. **No, revise first** — make changes before saving

Wait for the user's answer before writing.

3. **Iterate** on the draft based on user feedback. Only proceed to writing
   when the user approves.

### Step 4: Write the ADR

1. Create the configured decisions directory if it doesn't exist

2. **Populate frontmatter**: before writing the artifact file,
   substitute the unified base fields into the template's frontmatter
   block, using the metadata captured in Step 3.

   1. The `Current Date/Time (UTC):` value from
      `accelerator corpus metadata derive` is the source for `date:` and
      `last_updated:`. Repository identity is not part of the ADR
      provenance bundle (ADRs are not code-state-anchored).
   2. **Substitute** every field below with the indicated value:
      - `type:` ← `adr`
      - `id:` ← the ADR identifier `ADR-NNNN` from Step 1, always
        quoted as a YAML string (e.g. `id: "ADR-0042"`)
      - `title:` ← the ADR title (without the `ADR-NNNN:` prefix)
      - `date:` ← the `Current Date/Time (UTC):` value
      - `author:` ← the author resolved per the standard chain
        (config → VCS user → prompt)
      - `producer:` ← `create-adr`
      - `status:` ← `proposed`
      - `last_updated:` ← the same `Current Date/Time (UTC):` value
      - `last_updated_by:` ← the same value resolved for `author`
      - `schema_version:` ← `1` (bare integer)

      Optional linkage / decision-maker keys are omit-by-default:
      the template shows each as `""`/`[]`, but write a key
      into the artifact **only** when it has a value, and omit it
      entirely otherwise (do not carry the empty placeholder through).

      - `parent:` ← the owning work item as a typed-linkage ref
        (`"work-item:NNNN"`). Fill when the ADR is owned by a work item;
        otherwise omit the key.
      - `supersedes:` ← a YAML list of typed-linkage refs of the form
        `"adr:ADR-NNNN"` to the ADR(s) this one replaces. Fill when this
        ADR supersedes another; otherwise omit the key.
      - `relates_to:` ← list of typed-linkage refs to loosely related
        ADRs (`["adr:ADR-NNNN", ...]`). Fill when related decisions are
        explicit; otherwise omit the key.
      - `decision_makers:` ← a YAML list of the people who agreed to the
        decision. Fill when decision-makers are captured; otherwise omit
        the key.

3. Write the ADR to:
   `{decisions directory}/ADR-NNNN-description.md`
   where NNNN is the number from Step 1 and description is a kebab-case summary

4. If this supersedes an existing ADR:
   - Read the superseded ADR's current status to confirm it's `accepted`
   - Update ONLY the superseded ADR's frontmatter:
     - Change `status: accepted` to `status: superseded`
     - Add `superseded_by: ADR-MMMM` (where MMMM is the new ADR number)
   - Do NOT modify any other content in the superseded ADR
   - Append the new ADR's typed-linkage ref to the new ADR's
     `supersedes:` list (e.g. `["adr:ADR-0017"]`)

5. Present the result:

```
ADR created: `{decisions directory}/ADR-NNNN-description.md`
Status: proposed

[If supersession]: Updated ADR-XXXX status to "superseded"

Next steps:
- Review and refine while in "proposed" status
- When ready, use `/accelerator:review-adr` to accept or reject
```

**Validate the frontmatter**: after writing the ADR, run

```bash
accelerator corpus frontmatter validate --file {decisions directory}/ADR-NNNN-description.md
```

If it exits non-zero, the document violates the canonical frontmatter
standard; report the emitted violation and fix the frontmatter before
completing.

## ADR Template

Use this exact template structure when generating ADRs:

!`accelerator config template adr --fail-safe`

## Quality Guidelines

When drafting ADRs, follow these principles:

- **Concise**: One to two pages maximum. Match length to problem complexity.
- **Assertive**: Use active voice ("We will...", "We chose...")
- **Balanced**: Include genuine pros AND cons. Avoid the "Fairy Tale" pattern
  (only pros, no cons)
- **Honest options**: Only include options that were genuinely considered. Avoid
  "Dummy Alternatives" (non-viable options to make preferred choice look good)
- **Focused**: Each ADR captures ONE decision. If you find multiple decisions,
  suggest creating separate ADRs.
- **Context-rich**: Explain WHY, not just WHAT. Future readers need to
  understand the forces at play.

## Anti-Patterns to Avoid

- **Fairy Tale**: Only listing positive consequences
- **Dummy Alternative**: Including obviously non-viable options
- **Mega-ADR**: Multi-page documents crammed with implementation detail
- **Blueprint in Disguise**: Reads like a cookbook, not a decision journal
- **Missing context**: Decision without the forces that drove it

## Important Notes

- New ADRs ALWAYS start with status `proposed`
- ADR numbers are NEVER reused — always increment from the highest existing
- File naming is `ADR-NNNN-description.md` (e.g., `ADR-0001-use-jujutsu.md`)
- Only modify existing ADRs to update status fields during supersession
- Cross-reference related documents in the References section
- Use {documents locator agent} and {codebase locator agent} agents for context, not deep
  file reads in the main context
- **Dual status fields**: The template includes status in both YAML frontmatter
  (`status: proposed`) and the body (`**Status**: Proposed`). The frontmatter
  is the authoritative source of truth — `accelerator corpus adr read-status`
  reads only frontmatter. The body line is for human readability. When
  updating status, ALWAYS update both locations.
- Before writing a new ADR file, verify the target path does not already exist
  to prevent accidental overwrites from concurrent invocations

!`accelerator config instructions create-adr --fail-safe`