Record Knowledge

Record architectural decisions for future reference, and keep related feature specs in sync.

Record a decision

When a significant architectural or design choice is made, create an ADR:

1. Choose a decentralized ID in the form YYYY-MM-DD-short-title. The short title must be specific enough to remain unique among decisions created on the same date.
2. Confirm that docs/decisions/<id>.md does not already exist.
3. Create docs/decisions/<id>.md using the template below.
4. Update docs/decisions/INDEX.md with the new entry.
5. Reconcile specs — see "Update or create a spec" below.

Existing numeric ADR IDs remain valid and must not be renamed. References use the complete stable ID, for example ADR-2026-07-16-project-shell-output.

ADR template

# ADR-YYYY-MM-DD-short-title: Short Title

**Status:** accepted | superseded by <adr-id> | deprecated
**Date:** YYYY-MM-DD
**Area:** backend | frontend | infra | protocol | workflow

## Context
What situation prompted this decision. 2-5 sentences.

## Decision
What was decided. Reference file paths, packages, interfaces.

## Consequences
Trade-offs. What becomes easier or harder.

## Alternatives Considered
What else was considered and why it was rejected.

What warrants an ADR

Create an ADR only when all of these are true:

• The choice establishes a durable constraint, boundary, contract, ownership rule, operational invariant, or repo-wide convention.
• There were meaningful alternatives with materially different trade-offs.
• Future work will need to follow or deliberately supersede the choice.
• A spec, plan, code comment, or regression test alone would not preserve enough of the reasoning.

Typical examples include selecting a system-wide communication model, defining ownership across subsystems, changing a public API or persisted-data contract, and adopting a cross-cutting security or reliability invariant.

What does NOT need an ADR

• Simple features whose behavior belongs in a product spec
• Local implementation tactics and refactors within an existing pattern
• Routine dependency additions or upgrades
• Bug fixes unless they establish a new rule that future implementations must follow
• Plan sequencing, task breakdown, and temporary migration mechanics
• Anything obvious, uncontested, or easily reversible without cross-system consequences

Update or create a spec

ADRs capture why a decision was made. Specs capture what a feature does and why it exists. After recording an ADR, reconcile the affected spec — specs are the canonical product record kept in git, so they must stay accurate.

1. Read docs/specs/INDEX.md and identify any spec whose scope the decision touches (e.g., a routing decision affects office-provider-routing/spec.md).
2. For each affected spec:
   • If the decision changes observable behavior, scope, or scenarios: update docs/specs/<slug>/spec.md so the "What" and "Why" sections reflect the new direction. Add a Decision: ADR-<id> reference where relevant.
   • If the decision is purely internal (implementation choice with no spec-visible change): no spec edit needed — the ADR alone is sufficient.
3. If the decision introduces a new product feature that has no spec yet, invoke /spec to create one rather than writing it ad-hoc here.
4. If no spec applies (pure infra/process decision, like this knowledge system itself), skip — note in the ADR that no spec is needed.

Do not duplicate ADR content inside the spec. Specs reference ADRs; they don't restate them.