architecture-decision-record

name	architecture-decision-record
description	Generate structured Architecture Decision Records (ADRs) from architecture questions with trade-off analysis and auto-numbering
version	1.0

Architecture Decision Record (ADR) Generator

Purpose

Generate well-structured Architecture Decision Records that capture the context, decision, and consequences of significant architecture choices. ADRs create a searchable, chronological record of why decisions were made — not just what was decided.

When to Use

• A new technology, service, or architectural pattern is being evaluated
• A trade-off between two or more approaches needs to be documented
• A previous decision needs to be revisited or superseded
• Stakeholders need visibility into architecture rationale
• You want a durable record for compliance, audits, or onboarding

Workflow

Step 1: Capture the Decision Context

Ask the user for:

• Decision title — What are we deciding? (e.g., "Edge encryption approach for tactical deployments")
• Context — What problem or force is driving this decision?
• Stakeholders — Who is affected? Who has input?
• Constraints — Budget, timeline, compliance requirements, technical limitations
• Status — Is this a proposal, or has a decision already been made?

If the user provides a free-form description, extract these fields from their input.

Step 2: Research Alternatives

Using available tools, research the viable options:

• Search the codebase and local files for existing patterns, prior ADRs, or related decisions
• Search the web for industry best practices and reference architectures
• Review any referenced documents, specs, or RFCs
• Identify at least 2-3 viable alternatives (including "do nothing" if applicable)

Step 3: Analyze Trade-offs

For each alternative, evaluate along these dimensions:

• Pros — Benefits, strengths, alignment with constraints
• Cons — Risks, costs, complexity, operational burden
• Effort — Implementation complexity and estimated timeline
• Compliance — Regulatory, security, or accreditation implications
• Reversibility — How easy is it to change course later?

Step 4: Generate the ADR

Produce a markdown file using the template at docs/adr/template.md. Key sections:

1. Title — ADR-{NUMBER}: {Descriptive Title}
2. Date — Today's date
3. Status — Proposed | Accepted | Deprecated | Superseded by ADR-{N}
4. Context — The forces at play and why a decision is needed
5. Decision — The chosen approach, stated clearly and concisely
6. Alternatives Considered — Each option with pros/cons
7. Consequences — Positive, negative, and neutral impacts
8. References — Links to docs, prior ADRs, external resources

Step 5: File and Index

• Save to docs/adr/{NNNN}-{slug}.md (zero-padded 4-digit number)
• Auto-increment the ADR number by scanning existing files in docs/adr/
• If a docs/adr/README.md index exists, append the new entry
• If the ADR supersedes a previous one, update the old ADR's status

Output Format

The generated ADR must be:

• Self-contained — Readable without external context
• Concise — Aim for 1-2 pages; brevity over exhaustiveness
• Opinionated — State the recommendation clearly; don't just list options
• Timestamped — Every ADR captures the decision date for historical context

Tips

• ADRs are immutable once accepted — if circumstances change, create a new ADR that supersedes the old one
• Use plain language; avoid jargon that won't age well
• Link to related ADRs to build a decision graph over time
• "We chose X because Y" is more valuable than "X is the best option"