opencode-workflow/skills/write_adr/SKILL.md

name	description
write_adr	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:

### 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.

Anti-Placeholder Rule

Examples in this skill are illustrative only. Do not reuse placeholder ADR titles, contexts, decisions, or alternatives unless explicitly required by the PRD. Every ADR must document an actual architectural decision made for this system, with real context, real consequences, and real alternatives considered.

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.