Adr Write

What I do

• Create Architecture Decision Records (ADRs) following the Michael Nygard template
• Document the context, decision drivers, and constraints
• Enumerate considered alternatives with pros and cons
• Articulate consequences (positive, negative, and neutral)
• Assign a sequential ADR number and manage status lifecycle

When to use me

Use this skill when you need to:

• Document a significant architectural or technical decision
• Evaluate alternatives for a technology choice
• Record why a specific approach was chosen over others
• Create a decision log for a new or existing project
• Revisit or supersede a previous architectural decision

Process

1. Discover: Check for existing ADRs in the project

• Look for doc/adr/, docs/adr/, docs/decisions/, or adr/ directories
• Identify the numbering scheme and naming convention
• Read recent ADRs to match the project's style

1. Gather context: Understand the decision to be made

• What is the problem or requirement driving this decision?
• What are the constraints (technical, organizational, timeline)?
• Who are the stakeholders?

1. Enumerate alternatives: List all viable options

• For each option, document pros, cons, and trade-offs
• Include the "do nothing" option when relevant
• Reference benchmarks, documentation, or prior art

1. Draft the ADR: Write using the template below

1. Assign number and status: Follow the project's convention

• Number sequentially: 0001, 0002, etc.
• Set initial status to Proposed or Accepted

1. File the ADR: Save to the project's ADR directory

• Filename: NNNN-short-title.md (e.g., 0012-use-postgresql.md)

ADR Template

# ADR-NNNN: Title

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX

## Context

Describe the forces at play. What is the issue that motivates this decision?
Include technical context, business requirements, and constraints.

## Decision Drivers

- Driver 1 (e.g., performance requirements)
- Driver 2 (e.g., team expertise)
- Driver 3 (e.g., operational cost)

## Considered Alternatives

### Option A: [Name]
- **Pros:** ...
- **Cons:** ...

### Option B: [Name]
- **Pros:** ...
- **Cons:** ...

### Option C: [Name]
- **Pros:** ...
- **Cons:** ...

## Decision

State the decision clearly: "We will use [Option X] because..."

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Trade-off 1
- Trade-off 2

### Neutral
- Observation that is neither positive nor negative

## References

- [Link to relevant documentation]
- [Link to benchmark results]

ADR Status Lifecycle

Proposed -> Accepted -> (Deprecated | Superseded by ADR-XXXX)

• Proposed: Under discussion, not yet agreed upon
• Accepted: Decision has been agreed upon and is in effect
• Deprecated: Decision is no longer relevant
• Superseded: A newer ADR replaces this one (link to it)

Rules

• One decision per ADR; do not combine multiple decisions
• ADRs are immutable once accepted; create a new ADR to change a decision
• Always include at least two alternatives (including the chosen one)
• Write in neutral, factual tone; avoid advocacy language
• Keep ADRs concise: aim for 1-2 pages maximum
• Link to related ADRs when decisions are connected
• Store ADRs in version control alongside the code they describe

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: weisser-dev
• Source: weisser-dev/awesome-opencode
• License: MIT
• Homepage: https://www.npmjs.com/package/@weisser-dev/awesome-opencode

Install and usage instructions live in the source repository linked above.