Writing Architecture Documentation

Architecture docs in this repo serve two audiences: team members working on the system (need precise reference material) and team members seeking context (need an accessible narrative). The doc must work for both without requiring prior project context.

Before writing

1. Read at least two sibling docs in the same directory (e.g., other subsystem docs under docs/architecture docs/subsystems/). Calibrate your voice, structure, and level of detail to match them.
2. Read the ADRs you'll reference. Don't just link to them — understand them well enough to summarize the key idea inline, so the reader doesn't have to follow the link to understand the doc.

Voice and framing

Write about the system, not the project. These docs describe the intended system as far as we know it. They are not project retrospectives, sprint summaries, or PoC reports.

• State facts: "The execution pipeline generalizes across families" — not "The PoC validated that the execution pipeline generalizes"
• No transient project references: avoid "workstream", "PoC", "sprint", "milestone", "being validated", "current effort"
• No product comparisons: don't reference other products or prior versions. Describe what the system is, not what it improves upon.
• Non-goals are architectural boundaries, not "not yet done" items. No (current) qualifiers.

Write for a developer without prior context. Imagine someone joining the team and reading this doc as their first exposure to this part of the system.