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.

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.