Adr Writer

ADR Writer

Use this skill when the project needs a durable record of a major technical decision.

When to Use

• A significant architectural or technology choice is being made
• A decision spans multiple code changes or will matter to future contributors
• You need to document rejected alternatives and their tradeoffs
• An existing ADR needs to be superseded with a new decision

Purpose

Capture important technical decisions in adr_directory so future implementation work can understand the context, tradeoffs, and consequences.

Use an ADR for decisions that are broader than one code change and likely to matter again later.

Good ADR Candidates

• architecture or subsystem boundaries
• database or persistence strategy
• authentication or authorization approach
• external integration strategy
• deployment or infrastructure pattern
• major shared abstractions
• consequential performance or reliability tradeoffs

Avoid

• routine implementation details
• temporary coding tactics
• decisions that only affect one tiny local change
• rewriting history to make a decision look cleaner than it was

Output Location

Write ADRs to adr_directory.

File name format:

/0001-short-kebab-title.md

If ADRs already exist, continue the numbering.

ADR Template

# ADR 0001: Short Title

## Status
Proposed

## Context
What problem or pressure led to this decision?

## Decision
What are we deciding?

## Alternatives Considered
- Option A
- Option B

## Consequences
- Positive consequence
- Negative consequence
- Follow-up consequence

## Related Artifacts
- canonical PRD artifact
- related design doc, if any
- GitHub issue or PR

Writing Rules

• keep it concise and durable
• explain why, not just what
• name the rejected alternatives when they matter
• record tradeoffs honestly
• prefer one ADR per major decision
• update status if a proposed decision later becomes accepted, superseded, or rejected

Workflow Guidance

• read the related canonical PRD artifact, design doc, issue, plan, and any existing ADRs first
• avoid duplicating an existing ADR
• if a prior ADR is being changed, create a new ADR that supersedes it unless a minor edit is enough
• reference the ADR from the relevant issue or plan when appropriate

Inputs

• adr_directory – target directory path for ADR files. If not provided, defaults to docs/adr.
• Description of the decision to record, including context, alternatives considered, and consequences

Outputs

• A new numbered Markdown ADR file in adr_directory following the template format (e.g. 0001-short-kebab-title.md)

Examples

# Decision: use PostgreSQL instead of SQLite
adr_directory: docs/adr

Produces docs/adr/0001-use-postgresql.md with Status, Context, Decision, Alternatives, and Consequences sections.

Source & license

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

• Author: brpaz
• Source: brpaz/agent-skills
• License: MIT

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