Architecture Decision Record

Architecture Decision Record

Extracts key architectural decisions from technical-requirements.yaml and formalizes each one as a standalone ADR file. ADRs document why the system is built the way it is, not just what was chosen — making them essential for onboarding, audits, and revisiting trade-offs.

Prerequisites

• {base_directory}/requirements/technical-requirements.yaml (output from /technical-requirements-interview)

Usage

/architecture-decision-record [base-directory]

If no directory is provided, auto-detect by looking for requirements/technical-requirements.yaml in the current directory.

If not found, prompt the user: "Where are your requirements documents located?"

Wait for the user to provide a path before proceeding. Store as base_directory.

Process

Step 1: Determine Base Directory and Load Technical Requirements

If no directory parameter was provided, check if requirements/technical-requirements.yaml exists in the current directory.

• If found, use current directory as base_directory
• If not found, prompt: "Where are your requirements documents located?" and wait for user response

Once base_directory is determined, read {base_directory}/requirements/technical-requirements.yaml and identify every decision point. Look in these sections:

• architecture — patterns, frameworks, structural choices
• technology_stack — language, runtime, major libraries, databases
• data_model — storage engine choice, schema design decisions
• api_design — REST vs GraphQL vs RPC, versioning strategy
• security — auth mechanism, token strategy, encryption approach
• testing — testing strategy, coverage targets, tooling
• deployment — hosting, CI/CD pipeline, containerization
• trade_offs and open_questions — explicitly flagged decisions

Collect each decision as a candidate ADR. A decision qualifies if:

• It involves a meaningful choice between alternatives, OR
• It has notable consequences for the system's future flexibility, OR
• It was explicitly flagged as a trade-off or open question

Step 2: Identify Alternatives

For each candidate decision, reason about what the realistic alternatives were. Derive these from:

• The trade_offs section of the technical requirements (if present)
• Common alternatives for the chosen technology/pattern
• Any "options considered" language in the requirements

If no alternatives are inferable, note "alternatives not documented" rather than fabricating them.

Step 3: Assign ADR IDs and Titles

Number ADRs sequentially starting at ADR-001. Titles should be brief and declarative:

• Good: Use PostgreSQL as the primary data store
• Bad: Database decision

Group related decisions logically (e.g., all auth decisions before all deployment decisions).

Step 4: Write ADR Files

Create the directory structure:

mkdir -p {base_directory}/architecture/adrs

Write one file per ADR: {base_directory}/architecture/adrs/ADR-NNN-kebab-case-title.md

Each file follows this format:

The ADR document includes: header (ADR-NNN: Title, Status, Date, Source), and four required sections: Context (problem description), Decision (the choice made), Alternatives Considered (table of options ruled out), and Consequences (Positive, Negative/Trade-offs, Risks).

See [references/adr-document-spec.md](references/adr-document-spec.md) for the complete ADR document specification with all sections and formatting rules.

See [references/example-ADR-001.md](references/example-ADR-001.md) and [references/example-ADR-003.md](references/example-ADR-003.md) for full examples.

Step 5: Write INDEX.md

Create {base_directory}/architecture/adrs/INDEX.md as a summary table:

The index includes a single table with columns: ID (link), Title, Status, Date.

See [references/adr-index-spec.md](references/adr-index-spec.md) for the complete INDEX specification.

See [references/example-INDEX.md](references/example-INDEX.md) for a full example.

Step 6: Gap Analysis

Report inline after generating all files:

## ADR Gap Analysis

**Project:** [name]
**ADRs Generated:** [n]

**Decision Areas Covered:**
[✓ / ✗] Architecture / structural patterns
[✓ / ✗] Technology stack
[✓ / ✗] Data storage
[✓ / ✗] API design
[✓ / ✗] Security / authentication
[✓ / ✗] Testing strategy
[✓ / ✗] Deployment / infrastructure

**Open Questions carried forward:** [n]
[List any open_questions from technical-requirements.yaml that could not yet be
formalized as Accepted ADRs — these are candidates for future ADRs.]

**Recommendations:** [none / list]

Output Format

{base_directory}/architecture/adrs/
  INDEX.md
  ADR-001-[title].md
  ADR-002-[title].md
  ...

Example Output

See [references/](references/) for sample ADR files (ADR-001, ADR-003) and an INDEX.md.

ADR Document Specification (ADR-*.md)

Document Type: ADR-NNN-kebab-case-title.md (in architecture/adrs/ directory) Version: 1.0.0 Generated By: architecture-decision-record skill Purpose: Documents a significant architectural choice. Captures context, the decision made, alternatives considered, and consequences.

---

Document Structure

Header Section

# ADR-NNN: [Title]

**Status:** [Status]
**Date:** YYYY-MM-DD
**Source:** [Source document]

Validation Rules:

• Heading: Level-1 heading starting with "ADR-NNN: " where NNN is 3-digit zero-padded number
• Title: Brief declarative statement (10-80 characters)
• Status: Bold label with one of: Accepted, Proposed, Deprecated, Superseded
• Date: ISO 8601 format (YYYY-MM-DD); date decision was made/accepted
• Source: Document from which decision was extracted (typically "technical-requirements.yaml")

Context Section

## Context

[2-4 sentences describing the problem or decision that needed to be made.
What forces were at play? What constraints existed? Why did this need a decision?]

Validation Rules:

• Required section
• 2-4 sentences (100-400 characters recommended)
• Describes the problem space, not the solution
• Should answer: "Why was this decision necessary?"

Good Example: "The project requires a CLI tool distributed to developer workstations across multiple operating systems. The team has existing TypeScript expertise and the codebase already uses Node.js tooling. A statically-typed language was preferred to reduce runtime errors."

Poor Example: "We needed to choose a language." (too vague)

Decision Section

## Decision

[1-3 sentences stating the decision clearly and directly.
Start with "We will..." or "The system will..."]

Validation Rules:

• Required section
• 1-3 sentences (50-300 characters recommended)
• States the decision explicitly
• Uses declarative language ("We will...", "The system will...")

Good Example: "We will implement the CLI in TypeScript, compiled to a self-contained Node.js executable via pkg or esbuild. Distribution will be via npm as a globally installable package."

Poor Example: "Use TypeScript." (too terse; lacks implementation details)

Alternatives Considered Section

## Alternatives Considered

| Option | Reason not chosen |
|--------|-------------------|
| [Alternative 1] | [why ruled out] |
| [Alternative 2] | [why ruled out] |

[If alternatives are not documented in the requirements, write:
"Alternatives were not documented in the source requirements."]

Validation Rules:

• Required section
• Markdown table format OR fallback text
• Each alternative should be realistic (not strawman)
• Reasons should be specific to the project context

Table Format:

• Two columns: "Option" and "Reason not chosen"
• At least one row (if alternatives exist)
• Reasons should be 10-150 characters

Fallback Text: Use exact text "Alternatives were not documented in the source requirements." when no alternatives are documented.

Good Example:

| Option | Reason not chosen |
|--------|-------------------|
| Go | No existing team expertise; would require separate build pipeline |
| Python | Dynamic typing increases risk of runtime parse errors |

Consequences Section

## Consequences

### Positive
- [benefit 1]
- [benefit 2]

### Negative / Trade-offs
- [drawback or constraint this decision introduces]

### Risks
- [risk 1, if any]

Validation Rules:

• Required section
• Three subsections: Positive, Negative/Trade-offs, Risks
• Each subsection uses bullet points
• At least one positive and one negative consequence

Subsection Definitions:

Good Example:

### Positive
- Type safety catches schema mismatches at compile time
- npm distribution is familiar to target audience

### Negative / Trade-offs
- Node.js startup overhead (~100–200ms) on cold runs
- Larger binary size than Go equivalent (~40–60MB)

---

File Naming and Location

Naming Convention

Pattern: ADR-NNN-kebab-case-title.md

Rules:

• Prefix: ADR- (uppercase)
• Number: 3-digit zero-padded (001-999)
• Title: Kebab-case (lowercase, hyphens, no spaces)
• Extension: .md (markdown)

Examples:

• ✅ ADR-001-use-typescript-for-cli-implementation.md
• ✅ ADR-042-implement-jwt-based-authentication.md
• ❌ adr-1-typescript.md (lowercase prefix, not zero-padded)
• ❌ ADR-001-Use-TypeScript.md (not kebab-case)
• ❌ ADR-001.md (missing descriptive title)

Directory Structure

{base_directory}/
  architecture/
    adrs/
      INDEX.md
      ADR-001-use-typescript-for-cli-implementation.md
      ADR-002-use-yaml-for-workflow-definition-format.md
      ADR-003-use-postgresql-as-primary-data-store.md

Encoding

• UTF-8 encoding
• Unix line endings (LF)
• No trailing whitespace

---

Validation Rules

1. File name must match pattern ADR-\d{3}-[a-z0-9-]+\.md 2. Must contain all required sections: Context, Decision, Alternatives Considered, Consequences 3. Level-1 heading must start with "ADR-NNN:" matching file name number 4. Must contain metadata: Status, Date, Source 5. Context: 2-4 sentences describing problem space (not solution) 6. Decision: 1-3 sentences using declarative language ("We will...") 7. Alternatives: Table format OR "Alternatives were not documented..." fallback 8. Consequences: Must have Positive and Negative/Trade-offs subsections with ≥1 bullet each

---

Integration with Other Documents

Source Documents

• technical-requirements.yaml: Primary source for architectural decisions
• business-requirements.yaml: Provides context for why decisions matter

Referenced By

• INDEX.md: Master index linking to all ADR files
• Implementation tasks: Developers reference ADRs when making technical choices

Relationship to Other Documents

• ADRs document decisions, not implementation details
• One ADR per decision (don't combine multiple decisions)
• Once accepted, ADRs remain unchanged; status may update to Deprecated/Superseded
• ADRs may reference milestones but are independent of delivery timeline

---

Status Lifecycle

The architecture-decision-record skill generates all ADRs with status "Accepted". Other statuses (Proposed, Deprecated, Superseded) are applied manually when decisions change.

Status Transitions:

Accepted → Deprecated (when phasing out)
Accepted → Superseded by ADR-NNN (when replaced)

When superseding, update the old ADR's status field: **Status:** Superseded by ADR-012

---

See skills/architecture-decision-record/examples/ADR-001-use-typescript-for-cli-implementation.md for a complete working example.

---

---

Best Practices

Writing Context

• Focus on the problem, not the solution
• Include constraints that influenced the decision
• Be specific to this project (not generic industry context)

Stating the Decision

• Be declarative: "We will..." or "The system will..."
• Include implementation details
• Avoid hedging language: "might", "could", "probably"

Documenting Alternatives

• Include only realistic alternatives
• Provide specific reasons tied to project constraints
• Don't fabricate alternatives; use fallback text if unknown

Describing Consequences

• Be honest about trade-offs (all decisions have downsides)
• Quantify when possible (e.g., "~100–200ms startup overhead")
• Include risks even if mitigated

---

Common Issues

• Vague Context: "We needed to choose a database" → Be specific about requirements and constraints
• Non-Declarative Decision: "We picked PostgreSQL" → "We will use PostgreSQL 14+ as the primary data store"
• Missing Trade-offs: Always include at least one negative consequence; all decisions have costs
• Fabricated Alternatives: Use fallback text if alternatives are genuinely unknown

---

Metadata

• Specification Version: 1.0.0
• Last Updated: 2026-04-16
• Related Skills: architecture-decision-record
• Related Specs: adr-index-spec.md

ADR Index Specification (INDEX.md)

Document Type: INDEX.md (in architecture/adrs/ directory) Version: 1.0.0 Generated By: architecture-decision-record skill Purpose: Master index listing all Architecture Decision Records with metadata for quick reference and navigation.

---

Document Structure

Header Section

# Architecture Decision Records

Validation Rules:

• Must be a level-1 heading
• Exact text: "Architecture Decision Records"

ADR Table

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-001](ADR-001-title.md) | [Title] | [Status] | YYYY-MM-DD |
| [ADR-002](ADR-002-title.md) | [Title] | [Status] | YYYY-MM-DD |

Columns:

• ID: [ADR-NNN](ADR-NNN-kebab-case-title.md) where NNN is 3-digit zero-padded (001-999)
• Title: Brief declarative summary (10-80 characters, sentence case, no period)
• Status: One of Accepted, Proposed, Deprecated, Superseded
• Date: ISO 8601 format (YYYY-MM-DD)

Status Definitions

---

Ordering and Organization

Chronological Ordering

• ADRs are listed in ID sequence (ADR-001, ADR-002, etc.)
• IDs are assigned sequentially as decisions are documented
• IDs are never reused even if an ADR is deprecated

Logical Grouping

When generating ADRs from technical requirements, group related decisions by category (architecture, technology stack, data storage, API design, security, testing, deployment) to improve navigability.

---

File Location and Naming

Directory Structure

{base_directory}/
  architecture/
    adrs/
      INDEX.md                           # This file
      ADR-001-kebab-case-title.md
      ADR-002-kebab-case-title.md
      ...

File Naming Convention

• File name: INDEX.md (all caps, exactly)
• Location: architecture/adrs/ subdirectory
• Encoding: UTF-8
• Line endings: Unix (LF)

---

Validation Rules

1. Must contain exactly one level-1 heading: "Architecture Decision Records" 2. Must contain exactly one markdown table with 4 columns: ID, Title, Status, Date 3. Table must have at least one ADR row 4. IDs must be unique, match pattern ADR-\d{3}, and link to existing files 5. Titles must be 10-80 characters 6. Status must be one of: Accepted, Proposed, Deprecated, Superseded 7. Dates must be ISO 8601 format (YYYY-MM-DD) 8. All ADR files in the directory must have corresponding INDEX.md rows 9. ID numbers should be sequential starting at 001

---

Integration with Other Documents

Source Documents

• technical-requirements.yaml: Primary source for architectural decisions
• Individual ADR files: Each row links to a detailed ADR document

Used By

• Architecture documentation: Quick reference for all decisions
• Onboarding: New team members review architectural choices
• Decision tracking: Teams see evolution of decisions over time

Relationship to Other Documents

• INDEX.md is a summary; details are in individual ADR files
• ADRs may reference milestones but are independent of delivery timeline

---

Example Structure

# Architecture Decision Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-001](ADR-001-use-typescript-for-cli-implementation.md) | Use TypeScript for CLI implementation | Accepted | 2026-03-26 |
| [ADR-002](ADR-002-use-yaml-for-workflow-definition-format.md) | Use YAML for workflow definition format | Accepted | 2026-03-26 |
| [ADR-003](ADR-003-use-postgresql-as-primary-data-store.md) | Use PostgreSQL as primary data store | Accepted | 2026-03-27 |
| [ADR-004](ADR-004-implement-jwt-based-authentication.md) | Implement JWT-based authentication | Accepted | 2026-03-27 |

See skills/architecture-decision-record/examples/INDEX.md for a complete working example.

---

---

Best Practices

Title Writing

• Be declarative: "Use X" or "Implement Y", not "Decision about X"
• Be specific: "Use PostgreSQL as primary data store" not "Database choice"
• Be concise: Aim for 5-10 words

Status Management

• Default to "Accepted" for ADRs generated from finalized technical requirements
• Use "Proposed" sparingly; most ADRs document decided matters
• When superseding an ADR, update the old ADR header: "Superseded by ADR-NNN"
• Never delete deprecated ADRs; mark status as "Deprecated" instead

Maintenance

• Add new ADRs to the bottom of the table (sequential IDs)
• Update status when decisions change, but keep original date
• Use relative links (no absolute URLs)

---

Common Issues

• Duplicate IDs: Use highest existing ID + 1 for new ADRs
• Broken Links: Validate all linked ADR-*.md files exist in the adrs/ directory
• Status Ambiguity: Use "Accepted" by default; reserve other statuses for edge cases

---

Metadata

• Specification Version: 1.0.0
• Last Updated: 2026-04-16
• Related Skills: architecture-decision-record
• Related Specs: adr-document-spec.md

ADR-001: Use TypeScript for CLI implementation

Status: Accepted Date: 2026-03-26 Source: technical-requirements.yaml

Context

The project requires a CLI tool distributed to developer workstations across multiple operating systems. The team has existing TypeScript expertise and the codebase already uses Node.js tooling. A statically-typed language was preferred to reduce runtime errors in a tool that parses and executes user-defined workflow files.

Decision

We will implement the CLI in TypeScript, compiled to a self-contained Node.js executable via pkg or esbuild. Distribution will be via npm as a globally installable package.

Alternatives Considered

Consequences

Positive

• Type safety catches schema mismatches at compile time rather than runtime
• npm distribution is familiar to the target developer audience
• Existing TypeScript tooling (ESLint, Prettier, ts-jest) can be reused

Negative / Trade-offs

• Node.js startup overhead (~100–200ms) on cold runs; acceptable given the < 500ms target
• Distributed binary size is larger than a Go equivalent (~40–60MB with bundled Node runtime)

Risks

• Node.js version compatibility on end-user machines must be managed via .nvmrc and minimum-version checks at startup

ADR-003: Use PostgreSQL as primary data store

Status: Accepted Date: 2026-03-27 Source: technical-requirements.yaml

Context

The system requires sub-100ms query latency for user authentication lookups, ACID guarantees for transaction history, and the ability to scale to 10M users within 2 years. The data model includes complex relationships between users, workflows, and execution logs. Budget constraints favor open-source solutions over proprietary databases.

Decision

We will use PostgreSQL 14+ as the primary data store, hosted on AWS RDS with automated backups and read replicas for high-traffic queries. All transactional data (users, workflows, executions) will be stored in a normalized relational schema.

Alternatives Considered

Consequences

Positive

• ACID compliance ensures data integrity for critical workflow state transitions
• Rich JSON support (jsonb) allows flexible metadata storage without schema migrations
• Mature ecosystem with proven scalability (e.g., GitHub, Instagram use PostgreSQL)
• AWS RDS provides managed backups, monitoring, and automated failover

Negative / Trade-offs

• Vertical scaling has limits; will need read replicas and connection pooling beyond 1M concurrent users
• PostgreSQL expertise required on team for query optimization and index tuning
• Full-text search is adequate but not as powerful as dedicated search engines (Elasticsearch)

Risks

• Connection pool exhaustion under high traffic requires careful configuration (pgBouncer or RDS Proxy)
• Large-scale migrations (ALTER TABLE on multi-TB tables) require careful planning and downtime windows

Architecture Decision Records