Adr Drafting

# ADR Examples

## Example 1

**Path:** `docs/architecture/adr/0003-adopt-postgresql-for-primary-database.md`

```markdown
# ADR-0003: Adopt PostgreSQL for the Primary Database

## Status
Accepted

## Context
The application has outgrown SQLite for concurrent writes and operational visibility. We need stronger transactional guarantees, better backup tooling, and a database that can support production traffic growth.

## Decision
Adopt PostgreSQL as the primary relational database for all new production deployments.

## Consequences
PostgreSQL improves concurrency, operational tooling, and long-term scalability. It also introduces additional infrastructure and migration complexity compared with SQLite.
```

## Example 2

**Path:** `docs/architecture/adr/0004-introduce-event-driven-order-processing.md`

```markdown
# ADR-0004: Introduce Event-Driven Order Processing

## Status
Proposed

## Context
Synchronous order processing is increasing latency in the checkout flow and makes retries difficult when downstream services are degraded.

## Decision
Introduce an event-driven workflow for order fulfillment so checkout can publish an order event and downstream processors can handle fulfillment asynchronously.

## Consequences
This change should reduce user-facing latency and improve resilience. It also adds messaging infrastructure, operational monitoring needs, and eventual-consistency trade-offs.
```

## Naming Tips

- Prefer action-oriented titles such as "Adopt", "Introduce", "Standardize", or "Migrate"
- Keep filenames short but descriptive
- Reuse the repository's numbering pattern if ADRs already exist


# Default ADR Template

Use this template when the repository does not already provide an ADR structure.

```markdown
# ADR-NNNN: Decision Title

## Status
Proposed

## Context
Describe the problem, constraints, trade-offs, and any alternatives that influenced this decision.

## Decision
Describe the architectural choice that was made.

## Consequences
Describe what becomes easier, harder, riskier, or more expensive because of this decision.
```

## Default Conventions

- Directory: `docs/architecture/adr`
- Filename: `NNNN-short-kebab-title.md`
- Title format: `ADR-NNNN: Decision Title`
- Starting number: `0001` if no prior ADR exists

## Status Guidance

- `Proposed` — The change is being considered or prepared
- `Accepted` — The team has agreed to the decision
- `Rejected` — The proposed decision was considered and declined

Keep status values simple unless the repository already uses a richer ADR lifecycle.


---
name: adr-drafting
description: Creates new Architecture Decision Record (ADR) documents for significant architectural changes using a consistent template and repository-aware naming and storage guidance. Use when a user or agent decides on an architectural change, needs to document technical rationale, or wants to add a new ADR to the project history.
allowed-tools: Read, Write, Edit, Glob, AskUserQuestion
---

# ADR Drafting

Creates new Architecture Decision Record (ADR) documents for major architectural choices so teams can keep a clear history of why important technical decisions were made.

## Overview

This skill helps create a new ADR from discovery to final markdown file. It confirms the decision details, inspects the repository for any existing ADR conventions, and drafts a new ADR with the standard sections `Title`, `Status`, `Context`, `Decision`, and `Consequences`.

When the repository does not already have an ADR convention, default to storing ADRs in `docs/architecture/adr` and use a zero-padded filename such as `0001-use-postgresql-for-primary-database.md`.

See `references/template.md` for the default ADR template and `references/examples.md` for example ADRs and naming patterns.

## When to Use

Use this skill when a user or agent has decided on a meaningful architectural change and needs to document the rationale, chosen direction, and trade-offs in a new Architecture Decision Record. It fits r