name	create-adr
description	Create Architecture Decision Records (ADRs) following LCA conventions. INVOKE THIS SKILL when user: - Asks to "document a decision" or "record a decision" - Mentions "ADR", "decision record", or "architectural decision" - Wants to capture trade-offs or options considered - Needs to supersede or update an existing decision - Asks about decision history or rationale Trigger keywords: ADR, decision record, architectural decision, trade-offs, options, rationale
allowed-tools	Read, Write, Glob, AskUserQuestion

Guide creation of Architecture Decision Records that capture the "why" behind architectural choices. ADRs are append-only documents that preserve decision history, enabling future maintainers to understand context and trade-offs. 1. **Identify decision scope**: What architectural choice needs documentation? 2. **Gather context**: Why is this decision being made now? What drivers exist? 3. **Document options**: What alternatives were considered? 4. **Analyze trade-offs**: Explicit positive, negative, neutral consequences 5. **Record decision**: Write ADR with proper numbering and status 6. **Link to architecture docs**: Reference from relevant ARCHITECTURE.md ``` adr-NNN-{slug}.md

Examples: adr-001-use-protocol-buffers.md adr-002-adopt-event-sourcing.md adr-003-schema-org-boundaries.md


Numbers are sequential and never reused. Superseded ADRs keep their number.
</naming_convention>

<template>
```markdown
# ADR-NNN: {Title}

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date**: YYYY-MM-DD
**Deciders**: [list of people involved]
**Technical Story**: [ticket/issue reference if applicable]

## Context and Problem Statement

[Describe the context and problem. What forces are at play? Why is this decision needed now?]

## Decision Drivers

* [Driver 1: e.g., Performance requirements]
* [Driver 2: e.g., Team expertise]
* [Driver 3: e.g., Maintenance burden]

## Considered Options

1. [Option 1]
2. [Option 2]
3. [Option 3]

## Decision Outcome

**Chosen option**: "[Option N]" because [justification].

### Consequences

**Positive:**
* [Benefit 1]
* [Benefit 2]

**Negative:**
* [Drawback 1]
* [Drawback 2]

**Neutral:**
* [Side effect that is neither good nor bad]

## Pros and Cons of Options

### Option 1: [Name]

* Good, because [argument]
* Good, because [argument]
* Bad, because [argument]

### Option 2: [Name]

* Good, because [argument]
* Bad, because [argument]
* Bad, because [argument]

### Option 3: [Name]

[etc.]

## Links

* [Link to related ADRs]
* [Link to architecture documentation]
* [Link to external references]

| Status | Meaning | Action | |--------|---------|--------| | Proposed | Under discussion | Gather feedback, refine options | | Accepted | Decision made | Implement, update architecture docs | | Deprecated | No longer relevant | Document why, keep for history | | Superseded | Replaced by newer ADR | Link to superseding ADR | ADRs are **never deleted or modified** after acceptance. They are historical records.

To change a decision:

Create new ADR with next number
Reference original: "Supersedes ADR-NNN"
Update original status: "Superseded by ADR-XXX"

This preserves the decision trail and reasoning evolution.

- Start at 001 - Always 3 digits with leading zeros - Sequential, never skip numbers - Superseded ADRs keep their original number When gathering context, consider these common architectural drivers:

Technical:

Performance requirements (latency, throughput)
Scalability needs (horizontal, vertical)
Reliability requirements (uptime, fault tolerance)
Security constraints (compliance, data protection)

Organizational:

Team expertise and capacity
Time-to-market pressure
Budget constraints
Existing technology investments

Operational:

Maintenance burden
Monitoring and observability
Deployment complexity
Rollback capabilities

Strategic:

Vendor lock-in considerations
Future flexibility needs
Integration requirements
Standards compliance

Ask these questions to surface drivers:

"What problem is this decision solving?"
"What happens if we don't make this decision?"
"What constraints are non-negotiable?"
"Who will be affected by this decision?"
"How long do we expect this decision to remain valid?"

LCA mandates explicit trade-offs—never assume decisions are purely positive.

Positive consequences: What improves? What becomes easier? Negative consequences: What gets harder? What new problems emerge? Neutral consequences: What changes without clear good/bad valence?

For each option, evaluate against:

Criterion	Weight	Option 1	Option 2	Option 3
Performance	High	++	+	-
Maintainability	Medium	+	++	+
Team familiarity	Low	-	+	++
Migration effort	Medium	--	+	+

Use: ++ (strong positive), + (positive), 0 (neutral), - (negative), -- (strong negative)

Surface hidden costs explicitly:

Learning curve: Time for team to become proficient
Migration path: Effort to move from current state
Operational overhead: Ongoing maintenance burden
Technical debt: Future refactoring this creates
Lock-in: Difficulty switching away later

Architecture decisions frequently needed in LCA systems:

Boundary Decisions:

"Where should the Conduit boundary be?"
"What Protocol Buffer version to use?"
"How to version the API?"

Composition Decisions:

"How to decompose this into Atoms?"
"What should the Composite orchestrate?"
"Where does this logic belong?"

Data Strategy Decisions:

"What Schema.org types at boundaries?"
"How to model this internally?"
"Where is the mapping layer?"

Performance Tunnel Decisions:

"Is this bottleneck proven by profiling?"
"What optimization approach?"
"How to encapsulate complexity?"

```markdown # ADR-005: Use Schema.org/Product at API Boundary

Status: Accepted Date: 2025-01-15 Deciders: Architecture team

Context and Problem Statement

Our product catalog API needs to be consumable by AI agents and third-party integrations. We need a data format that is self-describing and follows industry standards.

Decision Drivers

AI agents need to understand our data semantically
Third-party integrations should work without custom documentation
Internal models need to remain optimized for computation

Considered Options

Custom JSON schema with documentation
Schema.org/Product with JSON-LD serialization
GraphQL with custom types

Decision Outcome

Chosen option: "Schema.org/Product with JSON-LD serialization" because it provides semantic interoperability for AI consumers while following established web standards.

Consequences

Positive:

AI agents can parse and understand our data without training
Follows LCA principle of Schema.org at boundaries
SEO benefits from structured data

Negative:

Schema.org types are verbose compared to internal models
Mapping layer adds complexity
Some product attributes don't map cleanly

Neutral:

Team needs to learn JSON-LD serialization

Links

Relates to ARCHITECTURE.md#data-strategy
Schema.org Product: https://schema.org/Product

</example_adr>
</lca_specific_adrs>

<directory_structure>
<placement>
ADRs live in a dedicated directory at the architecture level they affect:

project/ ├── ARCHITECTURE.md ├── adr/ │ ├── adr-001-initial-architecture.md │ ├── adr-002-use-protocol-buffers.md │ └── adr-003-schema-org-boundaries.md └── services/ └── order-service/ ├── architecture.md └── adr/ └── adr-001-caching-strategy.md

</placement>

<index>
Maintain an index file for discoverability:

```markdown
# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [001](adr-001-initial-architecture.md) | Initial Architecture | Accepted | 2025-01-01 |
| [002](adr-002-use-protocol-buffers.md) | Use Protocol Buffers | Accepted | 2025-01-05 |
| [003](adr-003-schema-org-boundaries.md) | Schema.org at Boundaries | Accepted | 2025-01-15 |

Before marking ADR Accepted:

Clear problem statement (why now?)
Decision drivers listed with rationale
At least 2 options considered
Chosen option clearly stated with justification
Positive consequences documented
Negative consequences documented (mandatory—no free lunches)
Neutral consequences considered
Links to related architecture docs
Proper numbering (adr-NNN format)
Date and deciders recorded

An ADR is complete when:

A future reader can understand WHY the decision was made
Trade-offs are explicit, not hidden
Alternative options are documented for historical context
Links connect to relevant architecture documentation
Status accurately reflects decision state

create-adr

Install Skill

SKILL.md