git.stella-ops.org/docs/adr/index.md

Architecture Decision Records (ADRs)

Architecture Decision Records document long-lived choices that shape StellaOps architecture, security posture, and operator experience. They complement RFCs by capturing the final call and the context that led to it.

When to file an ADR

• Decisions that affect cross-module contracts, persistence models, or external interfaces.
• Security or compliance controls with on-going operational ownership.
• Rollout strategies that require coordination across guilds or sprints.
• Reversals or deprecations of previously accepted ADRs.

Small, module-local refactors that do not modify public behaviour can live in commit messages instead.

Workflow at a glance

1. Copy docs/adr/0000-template.md to docs/adr/NNNN-short-slug.md with a zero-padded sequence (see Numbering).
2. Fill in context, decision, consequences, and alternatives. Include links to RFCs, issues, benchmarks, or experiments.
3. Request async review from the impacted guilds. Capture sign-offs in the Deciders field.
4. Merge the ADR with the code/config changes (or in a preparatory PR).
5. Announce the accepted ADR in the Docs Guild channel or sprint notes so downstream teams can consume it.

Numbering and status

• Use zero-padded integers (e.g., 0001, 0002) in file names and the document header. Increment from the highest existing number.
• Valid statuses: Proposed, Accepted, Rejected, Deprecated, Superseded. Update the status when follow-up work lands.
• When an ADR supersedes another, link them in both documents’ References sections.

Review expectations

• Highlight edge-case handling, trade-offs, and determinism requirements.
• Include operational checklists for any new runtime path (quota updates, schema migrations, credential rotation, etc.).
• Attach diagrams under docs/adr/assets/ when visuals improve comprehension.
• Add TODO tasks for follow-up work in the relevant module’s TASKS.md and link them from the ADR.

Verification checklist

• Status, Date, Authors, and Deciders populated.
• Links to code/config PRs or experiments recorded under References.
• Consequences call out migration or rollback steps.
• Announcement posted to Docs Guild updates (or sprint log).

Related resources

• Docs Guild Task Board
• High-Level Architecture Overview
• Coding Standards
• Release Engineering Playbook