Architecture Decision Records

You are creating or managing Architecture Decision Records (ADRs) for this project.

Red Flags - STOP if you're

• Creating an ADR without understanding the decision context
• Documenting trivial decisions that don't warrant an ADR (e.g., variable naming)
• Writing an ADR after the fact without capturing the original reasoning
• Listing alternatives without genuine pros/cons analysis
• Skipping the "Consequences" section (the most valuable part)
• Not checking existing ADRs for conflicts or superseded decisions

ADRs capture WHY, not just WHAT. Every decision needs alternatives considered.

Pre-Check

1. Verify Draft is initialized:

ls draft/ 2>/dev/null

If draft/ doesn't exist:

• Tell user: "Project not initialized. Run /draft:init first."
• Stop here.

2. Check for existing ADR directory:

ls draft/adrs/ 2>/dev/null

If draft/adrs/ doesn't exist, create it:

mkdir -p draft/adrs

Step 1: Parse Arguments

Check for arguments:

• /draft:adr — Interactive mode: ask about the decision
• /draft:adr "decision title" — Create ADR with given title
• /draft:adr list — List all existing ADRs
• /draft:adr supersede <number> — Mark an ADR as superseded

List Mode

If argument is list:

1. Prefer the deterministic adr-index.sh wrapper for the listing — it returns a structured JSON {adrs:[{id,title,date,status,path,related_tracks}]} derived from each ADR's frontmatter. Resolve via the canonical tool resolver (see core/shared/tool-resolver.md):

   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
   if [ -x "$DRAFT_TOOLS/adr-index.sh" ]; then
     bash "$DRAFT_TOOLS/adr-index.sh" --root draft/adrs
   else
     ls draft/adrs/ # fallback: enumerate files manually
   fi

2. Display summary table:

Architecture Decision Records

| # | Title | Status | Date |
|---|-------|--------|------|
| 001 | Use PostgreSQL for primary storage | Accepted | 2026-01-15 |
| 002 | Adopt event-driven architecture | Proposed | 2026-02-01 |
| 003 | Replace REST with GraphQL | Superseded by #005 | 2026-02-03 |

Stop here after listing.

Supersede Mode

If argument is supersede <number>:

1. Read the ADR file draft/adrs/<number>-*.md
2. Change status from Accepted to Superseded by ADR-<new_number>
3. In the OLD ADR's References section, add: "Superseded by ADR-<new_number>"
4. Ask what new ADR supersedes it, or create the new one
5. In the NEW ADR's References section, add: "Supersedes ADR-<old_number>"
6. Stop here after updating.

Evaluate Mode

If argument starts with evaluate:

• /draft:adr evaluate <proposal or description> — Evaluate a design proposal

1. Read the proposal (from arguments, pasted text, file path, or ask user to describe)
2. Load project context: draft/tech-stack.md, draft/.ai-context.md, draft/architecture.md
3. Check existing ADRs in draft/adrs/ for related decisions
4. Evaluate against six dimensions:
   • Architecture alignment: Does it fit current patterns?
   • Tech stack consistency: Does it introduce technology not in tech-stack.md?
   • Invariant impact: Does it affect critical invariants from .ai-context.md?
   • Scalability: How does it scale with data/users/team growth?
   • Operational complexity: What new operational burden does it add?
   • Team familiarity: Does the team have experience with this approach?
5. Output evaluation report (do not save to file — display directly):

# Design Evaluation: <Title>

## Summary
[1-2 sentence assessment]

## Alignment Analysis
| Dimension | Assessment | Notes |
|-----------|------------|-------|
| Architecture alignment | ✅ Aligned / ⚠️ Partial / ❌ Conflict | [detail] |
| Tech stack consistency | ✅/⚠️/❌ | [detail] |
| Invariant impact | ✅/⚠️/❌ | [detail] |
| Scalability | ✅/⚠️/❌ | [detail] |
| Operational complexity | ✅/⚠️/❌ | [detail] |
| Team familiarity | ✅/⚠️/❌ | [detail] |

## Risks
- [Risk and mitigation strategy]

## Recommendation
[Accept as-is / Accept with modifications / Reconsider approach / Reject — with reasoning]

## Next Steps
If this leads to a decision: `/draft:adr "<decision title>"` to document it
If this needs a full design: `/draft:adr design "<system>"` to design it

Stop here after evaluation.

Design Mode

If argument starts with design:

• /draft:adr design <system or component> — Full system/component design

1. Gather requirements:
   • Ask user or extract from arguments: What does it need to do?
   • Functional requirements — Features and behaviors
   • Non-functional requirements — Scale, latency, availability, cost targets
   • Constraints — Team size, timeline, existing tech stack (from draft/tech-stack.md)
2. Load project context: same as ADR creation (Step 3 of main flow)

3. Design using 5-section framework:

   Section 1: Requirements

   • Functional requirements (bulleted list)
   • Non-functional requirements (table: dimension, target, rationale)
   • Constraints and assumptions

   Section 2: High-Level Design

   • Component diagram (ASCII)
   • Data flow description
   • API contracts (key endpoints/interfaces)
   • Storage choices with rationale

   Section 3: Deep Dive

   • Data model design (key entities and relationships)
   • API endpoint design (REST/GraphQL/gRPC with examples)
   • Caching strategy (what, where, TTL, invalidation)
   • Queue/event design (if applicable)
   • Error handling and retry logic

   Section 4: Scale & Reliability

   • Load estimation (requests/sec, data growth)
   • Scaling strategy (horizontal vs vertical)
   • Failover and redundancy
   • Monitoring and alerting requirements

   Section 5: Trade-off Analysis

   • Key trade-offs made (table: decision, alternative, why this choice)
   • What to revisit as the system grows
   • Risks and mitigations
4. Determine design document number using same ADR numbering (Step 4 of main flow)
5. Save to draft/adrs/<number>-design-<kebab-case-title>.md with YAML frontmatter and git metadata (same format as ADR creation, Step 5)
6. Present for review (same as Step 6 of main flow)

Stop here after design.

Step 2: Gather Decision Context

If in interactive mode (no title provided), ask:

1. "What technical decision needs to be documented?"
2. "What's the context? What forces are driving this decision?"
3. "What alternatives did you consider?"

If title provided, proceed directly with the title.

2.1 HLD Handoff (when invoked from a track context)

If an active track exists and draft/tracks/<id>/hld.md is present:

1. Read HLD §Alternatives Considered table.

2. If any row is marked Promote to ADR? yes and has not been promoted yet (no matching ADR exists), offer:

   Found 1 unpromoted alternative in <track>/hld.md:
     - {alternative} — rejected because: {reason}
   Promote to ADR? [Y/n]

3. When promoting:
   • Pre-fill ADR §Context from HLD §Background and the §High-Level Design / Key Design Decisions row that drove this rejection.
   • Pre-fill ADR §Decision from the HLD §Key Design Decision that was selected over this alternative.
   • Pre-fill ADR §Alternatives Considered with the rejected alternative.
   • Set frontmatter originating_hld: draft/tracks/<id>/hld.md.
4. After ADR creation, edit HLD §Alternatives Considered table: change the Promote to ADR? cell to ADR-<number> (linking back). Surface the diff to the user for confirmation.

If invoked outside a track context, skip 2.1 and proceed with normal interactive flow.

Step 3: Load Project Context

Follow the base procedure in core/shared/draft-context-loading.md.

Read relevant Draft context:

• draft/.ai-context.md — Current architecture patterns, invariants, data paths, and constraints. Falls back to draft/architecture.md for legacy projects.
• draft/tech-stack.md — Current technology choices
• draft/product.md — Product requirements that influence the decision

Cross-reference the decision against existing context:

• Does it align with documented architecture patterns?
• Does it introduce a new technology not in tech-stack.md?
• Does it affect product requirements?

Step 4: Determine ADR Number

# Extract the highest existing ADR number from filenames
ls draft/adrs/*.md 2>/dev/null | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1

Next number = highest existing ADR number + 1, zero-padded to 3 digits (001, 002, ...). If no ADRs exist, start at 001.

Verify the target filename draft/adrs/<number>-<kebab-case-title>.md does not already exist. If collision, increment the number until a free slot is found.

Step 5: Create ADR File

MANDATORY: Include YAML frontmatter with git metadata. Gather git info first:

git branch --show-current # LOCAL_BRANCH
git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "none" # REMOTE/BRANCH
git rev-parse HEAD # FULL_SHA
git rev-parse --short HEAD # SHORT_SHA
git log -1 --format=%ci HEAD # COMMIT_DATE
git log -1 --format=%s HEAD # COMMIT_MESSAGE
git status --porcelain | head -1 | wc -l # 0 = clean, >0 = dirty

Create draft/adrs/<number>-<kebab-case-title>.md:

---
project: "{PROJECT_NAME}"
module: "root"
adr_number: <number>
generated_by: "draft:adr"
generated_at: "{ISO_TIMESTAMP}"
git:
  branch: "{LOCAL_BRANCH}"
  remote: "{REMOTE/BRANCH}"
  commit: "{FULL_SHA}"
  commit_short: "{SHORT_SHA}"
  commit_date: "{COMMIT_DATE}"
  commit_message: "{COMMIT_MESSAGE}"
  dirty: {true|false}
synced_to_commit: "{FULL_SHA}"
# Optional — populated when ADR is promoted from a track HLD §Alternatives Considered row.
originating_hld: "{path/to/draft/tracks/<id>/hld.md or null}"
originating_track: "{<track_id> or null}"
---

# ADR-<number>: <Title>

| Field | Value |
|-------|-------|
| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
| **Generated** | {ISO_TIMESTAMP} |
| **Synced To** | `{FULL_SHA}` |

**Status:** Proposed
**Deciders:** [names or roles]

## Context

[What is the issue that we're seeing that is motivating this decision or change?]
[What forces are at play (technical, business, organizational)?]

## Decision

[What is the change that we're proposing and/or doing?]
[State the decision in active voice: "We will..."]

## Alternatives Considered

### Alternative 1: <name>
- **Pros:** [advantages]
- **Cons:** [disadvantages]
- **Why rejected:** [specific reason]

### Alternative 2: <name>
- **Pros:** [advantages]
- **Cons:** [disadvantages]
- **Why rejected:** [specific reason]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Risks
- [Risk and mitigation]

## References

- [Link to relevant discussion, RFC, or documentation]
- [Related ADRs: ADR-xxx]
- [Originating HLD: draft/tracks/<id>/hld.md §Alternatives Considered] (only when promoted from a track)

Step 6: Present for Review

Present the ADR to the user for review:

ADR-<number> created: <title>
File: draft/adrs/<number>-<kebab-case-title>.md
Status: Proposed

Review the ADR and update status to "Accepted" when approved.

Step 7: Update References (if applicable)

If the decision affects existing Draft context:

1. tech-stack.md — If introducing or removing technology, note: "Consider updating draft/tech-stack.md to reflect this decision."
2. architecture.md — If changing architectural patterns, note: "Consider updating draft/architecture.md to reflect this decision (.ai-context.md will be auto-refreshed via Condensation Subroutine)."
3. Superseded ADRs — If this decision replaces a previous one, update the old ADR's status.

ADR Status Lifecycle

Proposed → Accepted → [Deprecated | Superseded by ADR-xxx]

• Proposed — Decision documented, awaiting review
• Accepted — Decision approved and in effect
• Deprecated — Decision no longer relevant (context changed)
• Superseded — Replaced by a newer decision (link to replacement)

Error Handling

If no draft/ directory:

• Tell user to run /draft:init first

If ADR number conflict:

• Increment to next available number
• Warn: "ADR-<number> already exists. Using ADR-<next>."

If superseding non-existent ADR:

• Warn: "ADR-<number> not found. Check draft/adrs/ for valid ADR numbers."