---
name: write_adr
description: "Produce Architectural Decision Records with Context, Decision, Consequences, and Alternatives. A deliverable skill referenced by design-architecture."
---

This skill provides guidance and format requirements for producing Architectural Decision Records (ADRs) within the architecture document.

This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when documenting significant architectural decisions.

## Purpose

The Architect must document significant architectural decisions using the ADR format. ADRs provide a permanent record of the context, decision, consequences, and alternatives considered for each important choice.

## When to Write an ADR

Write an ADR for any decision that:
- Affects the system structure or service boundaries
- Involves a technology selection (language, framework, database, queue, cache, infra)
- Involves a consistency model choice (strong vs eventual, idempotency strategy)
- Involves a security architecture decision
- Involves a significant trade-off (performance vs consistency, complexity vs simplicity)
- Would be difficult or costly to reverse
- Other engineers would question "why was this chosen?"

## ADR Format

Each ADR must follow this format:

```markdown
### ADR-{N}: {Decision Title}

- **Context**: Why this decision was needed. What is the problem or situation that requires a decision? Which PRD requirements drove this decision? What constraints exist?

- **Decision**: What was decided. State the decision clearly and specifically. Include the specific technology, pattern, or approach chosen.

- **Consequences**: What trade-offs or implications result from this decision. Include both positive and negative consequences. Address:
  - What becomes easier?
  - What becomes harder?
  - What are the risks?
  - What are the operational implications?

- **Alternatives**: What other options were considered. For each alternative:
  - Brief description
  - Why it was not chosen
  - Under what circumstances it might be the better choice
```

## ADR Numbering

- Start with ADR-001 for the first decision
- Number sequentially (ADR-001, ADR-002, etc.)
- Each ADR in the architecture document gets a unique number

## ADR Examples

### ADR-001: Use Cassandra for Job Storage

- **Context**: The system needs to handle high write throughput (10,000+ writes/second) for job status updates. Jobs are write-once with frequent status updates. Queries are primarily by job ID and by status+created_at. The PRD requires 99.9% availability for job status writes.

- **Decision**: Use Cassandra as the primary storage for job data. Use PostgreSQL for relational data that requires complex queries and transactions.

- **Consequences**:
  - (+) High write throughput for job status updates
  - (+) Horizontal scalability for job storage
  - (+) 99.9% availability for job writes
  - (-) Eventual consistency for job reads (stale reads possible within replication window)
  - (-) No complex joins for job data
  - (-) Additional operational complexity of managing two database systems
  - (-) Data migration if requirements change

- **Alternatives**:
  - PostgreSQL only: Simpler operations, but may not handle write throughput under peak load. Would be appropriate if write throughput stays below 5,000 writes/second.
  - MongoDB: Good balance of write throughput and query flexibility, but less mature for time-series-like access patterns.
  - Redis + PostgreSQL: Redis for hot job data, PostgreSQL for cold storage. Adds complexity of data synchronization.

### ADR-002: Use Event-Driven Architecture for Order Processing

- **Context**: The PRD requires orders to be processed asynchronously with decoupled services. Order processing involves multiple steps (validation, payment, inventory, notification) that may fail independently. Each step must be retryable.

- **Decision**: Use event-driven architecture with the outbox pattern for order processing. Publish OrderCreated events from the Order Service, consumed by downstream services.

- **Consequences**:
  - (+) Services are decoupled and can evolve independently
  - (+) Individual steps can be retried without reprocessing the entire order
  - (+) Natural fit for saga pattern for distributed transactions
  - (-) Eventual consistency — downstream services may see stale data
  - (-) More complex debugging and tracing
  - (-) Requires outbox pattern implementation to ensure at-least-once delivery

- **Alternatives**:
  - Synchronous orchestration: Simpler to implement and debug, but creates tight coupling and doesn't handle partial failures well. Appropriate for simple, synchronous workflows.
  - Saga orchestration with a central coordinator: More control over flow, but adds a single point of failure and operational complexity.

## Embedding in Architecture Document

All ADRs must be embedded within the `## ADR` section of `docs/architecture/{feature}.md`.

Do NOT produce separate ADR files. All ADRs must be within the single architecture document.