What

Create Architectural Decision Records (ADRs) for each ecosystem project,
documenting the key design decisions that shaped the current architecture.
Currently only pacs_system has 2 ADRs; the other 7 projects have none.

Why

ADRs capture the why behind architectural choices. Without them, contributors
must reverse-engineer design rationale from code, or make changes that conflict
with intentional design decisions. ADRs prevent architectural regression and
accelerate onboarding for new contributors.

Where

How

ADR Template

---
doc_id: "{PREFIX}-ADR-{NNN}"
doc_title: "ADR-{NNN}: {Title}"
doc_date: "YYYY-MM-DD"
doc_status: "Accepted"
project: "{project_name}"
category: "ADR"
---

# ADR-{NNN}: {Title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-XXX}

## Context
{What is the issue or decision that needs to be made?}

## Decision
{What was decided and why?}

## Alternatives Considered
{What other options were evaluated?}

## Consequences
{What are the positive and negative consequences of this decision?}

Priority ADR Topics Per Project

File Location

docs/adr/
├── ADR-001-{topic}.md
├── ADR-002-{topic}.md
└── ADR-003-{topic}.md

Implementation Steps

1. Create docs/adr/ directory in each project
2. Write ADR-001 for each project (highest-impact decision)
3. Write ADR-002 and ADR-003 for each project
4. Add ADR entries to the SSOT registry (docs/README.md)
5. Cross-reference ADRs from relevant ARCHITECTURE.md sections

Acceptance Criteria

• docs/adr/ directory exists in all 8 projects
• Each project has at least 2 ADRs
• All ADRs follow the standard template
• ADRs have YAML frontmatter with doc_id
• ADRs are listed in each project's SSOT registry
• ARCHITECTURE.md files reference relevant ADRs

Related

• Part of docs: Ecosystem documentation improvement — enterprise-level standardization #559 (Ecosystem documentation improvement)
• Depends on docs: Add YAML frontmatter to all docs/ markdown files #562 (YAML frontmatter — doc_id format)
• Depends on docs: Create SSOT documentation registry per project #563 (SSOT registry — ADR listing)