create-adr

name	create-adr
description	Create Architecture Decision Records (ADRs) documenting key architectural choices. Analyzes context, evaluates alternatives, and captures decisions using standard ADR template. Use when documenting database design, technology selection, pattern choices, or architectural trade-offs.
acceptance	[{"adr_complete":"ADR document created with all required sections"},{"alternatives_analyzed":"At least 2 alternatives evaluated with pros/cons"},{"rationale_clear":"Decision rationale clearly explained"},{"consequences_documented":"Positive and negative consequences identified"}]
inputs	{"context":{"type":"string","required":true,"description":"Decision context (e.g., file path to analyze, or description of decision)","validation":"Must describe what decision needs to be made or what to analyze"},"decision_number":{"type":"number","required":false,"description":"ADR number (auto-incremented if not provided)"}}
outputs	{"adr_created":{"type":"boolean","description":"Whether ADR was successfully created"},"adr_path":{"type":"string","description":"Path to created ADR file"},"decision_number":{"type":"number","description":"ADR number assigned"}}
telemetry	{"emit":"skill.create-adr.completed","track":["decision_number","context_type","alternatives_count","duration_ms"]}

Create Architecture Decision Record (ADR)

Overview

Create comprehensive Architecture Decision Records following industry best practices. ADRs document architectural choices, alternatives considered, rationale, and consequences to provide context for future development.

ADR Structure:

• Context: Problem and constraints
• Decision: What was decided
• Alternatives: Options evaluated with pros/cons
• Rationale: Why this decision was made
• Consequences: Positive, negative, and neutral impacts

Prerequisites

• docs/adrs/ directory (created if missing)
• Context for decision (file to analyze, problem description, or existing architecture)

---

Workflow

Step 0: Determine ADR Number

Action: Find next available ADR number.

# List existing ADRs
ls -la docs/adrs/ 2>/dev/null || echo "ADR directory does not exist"

# Find highest number
find docs/adrs/ -name "adr-*.md" 2>/dev/null | \
  sed 's/.*adr-\([0-9]*\)-.*/\1/' | \
  sort -n | \
  tail -1

Calculate next number:

• If no ADRs exist: Start at 001
• If ADRs exist: Increment highest by 1

Create ADR directory if missing:

mkdir -p docs/adrs

---

Step 1: Analyze Context

Action: Understand what decision needs to be documented.

Context Types:

1. File/Schema Analysis (like Prisma schema):

# Read the file to analyze
Read(file_path: {context_path})

Analyze to identify:

• Technology choices: Database, ORM, patterns used
• Data modeling decisions: Schema structure, relationships
• Architectural patterns: Multi-tenancy, event sourcing, etc.