Architecture Decision Record (ADR) Skill

Purpose

Document significant architectural decisions so institutional knowledge persists across conversations and team members. ADRs capture the why, not just the what.

When to Invoke

• During Research phase (phase-research.md) when a significant architecture decision is identified
• When user explicitly asks to document a decision
• When choosing between 2+ viable approaches
• When introducing a new dependency or pattern
• When changing existing architecture

ADR Storage

ADRs are stored in docs/decisions/ as numbered files:

docs/decisions/
├── 0001-use-postgresql-for-storage.md
├── 0002-adopt-feature-based-structure.md
├── 0003-use-testcontainers-for-integration.md
└── NNNN-short-title.md

ADR Template

Create the ADR file at docs/decisions/NNNN-short-title.md (e.g., 0001-use-postgresql-for-storage.md):

ID conventions

An ADR has three identifiers — each serves a different purpose:

Identifier	Convention	Example	Purpose
File name	NNNN-short-title.md	0001-use-postgresql-for-storage.md	Human navigation in docs/decisions/
spec_id (frontmatter)	ADR-NNNN-SHORT-SLUG-VN	ADR-0001-USE-POSTGRESQL-V1	Globally unique document ID for cross-references
id (annotation)	ADR-NNNN	ADR-0001	Annotation-level decision ID for traceability links

The file number (NNNN) is the single source of truth — spec_id and annotation id derive from it.

Template

---
$schema: "https://raw.githubusercontent.com/irahardianto/awesome-agv/main/.agents/skills/structured-spec/spec-schema.json"
spec_id: "ADR-0001-USE-POSTGRESQL-V1"
title: "Use PostgreSQL for primary storage"
doc_type: "adr"
status: "proposed"
version: "1.0.0"
owners: ["platform-team"]
created: "2026-08-20"
modified: "2026-08-20"
---

<!-- decision
  id: ADR-0001
  title: Use PostgreSQL for primary storage
  status: proposed
  context: The application needs a relational database with ACID transactions, JSON support, and row-level security for multi-tenant isolation.
  alternatives: ["PostgreSQL", "MySQL", "CockroachDB"]
  rationale: PostgreSQL provides the best combination of JSONB support, RLS, and ecosystem maturity for our scale.
  consequences: Operational complexity of managing PostgreSQL in production. Team must learn RLS patterns. Limits future migration to non-relational stores.
  affects_requirements: [REQ-DATA-001]
-->

## Context
What is the issue that we're seeing that is motivating this decision?
Include technical constraints, business requirements, and relevant context.

## Decision
We chose **PostgreSQL** as the primary storage engine.

## Alternatives Considered

### Option A: PostgreSQL
- **Pros:** JSONB, RLS, mature ecosystem, strong community
- **Cons:** Operational overhead, single-node write bottleneck at extreme scale
- **Effort:** Low (team has experience)

### Option B: MySQL
- **Pros:** Widely deployed, good tooling
- **Cons:** No native RLS, weaker JSON support, less extensible
- **Effort:** Low

### Option C: CockroachDB
- **Pros:** Distributed SQL, automatic sharding, PostgreSQL-compatible wire protocol
- **Cons:** Younger ecosystem, higher operational complexity, cost at scale
- **Effort:** Medium (unfamiliar tooling)

## Rationale
PostgreSQL provides the best combination of JSONB support, row-level security, and ecosystem maturity for our current scale. CockroachDB was a strong contender but adds operational complexity we don't need until we outgrow single-node writes.

## Consequences

### Positive
- JSONB enables flexible schema evolution without migrations for non-critical fields
- RLS simplifies multi-tenant data isolation at the database layer

### Negative
- Team must learn RLS policy patterns (training cost)
- Single-node write bottleneck may require sharding at >10K TPS

### Risks
- Migration to a non-relational store would be costly if requirements shift
- RLS misconfiguration could expose tenant data (mitigated by integration tests)

## Related
- Architectural Patterns @architectural-pattern.md
- Database Design Principles @database-design-principles.md

Process Guidelines

1. Number sequentially — check existing ADRs in docs/decisions/ for the next number
2. Keep titles short — descriptive enough to identify the decision at a glance
3. Status lifecycle: proposed → accepted (after approval) → optionally deprecated or superseded
4. Never delete ADRs — if a decision is reversed, mark as superseded (with superseded_by in frontmatter) and create a new ADR
5. Use Sequential Thinking skill if the trade-off analysis is complex

Structured Spec Integration

• Cross-reference: See structured-spec/profiles/adr.md for full annotation field reference and additional rules.
• Standalone vs embedded: Standalone ADRs live in docs/decisions/; decisions scoped to a single SDD/PRD should be embedded as <!-- decision --> annotations within that document.
• Completeness: When status is accepted, verify the ADR satisfies specification.md §6 and profiles/adr.md additional rules.
• Annotation fields reference: Point to specification.md §4.5 for the complete field table.

Rule Compliance

ADRs should reference applicable rules:

• Architectural Patterns @architectural-pattern.md
• Core Design Principles @core-design-principles.md
• Project Structure @project-structure.md