Docs: Cleaned up ADR home page with better descriptions of content

2026-02-16 23:49:18 -05:00
parent ee5f0376d7
commit 96ceedbef4
1 changed files with 30 additions and 18 deletions
@@ -22,29 +22,41 @@ Presented as plain text fields at the top of each ADR, one per line:

 ### Content Sections

-| Section | Purpose |
-|---------|---------|
-| **Context** | The problem or situation that motivated this decision. Why it exists. |
-| **Decision** | The architectural choice that was made, stated declaratively. |
-| **Design** | Structural details — components, interfaces, patterns, data models, protocols. |
-| **Constraints** | Explicit rules and restrictions imposed on the codebase. Enforceable invariants. |
-| **Consequences** | Positive outcomes, negative trade-offs, and risks introduced by the decision. |
-| **Alternatives Considered** | Other options evaluated and why they were not chosen. May be "None — specification-driven requirement." |
-| **Compliance** | How adherence to this decision is verified (CI checks, linting, code review, test patterns). |
+#### Context

-### Related ADRs
+Describes the problem, situation, or forces that motivated the decision. This section explains *why* the ADR exists — what technical challenge, scaling concern, or design tension required an explicit architectural choice. It should give a reader who is unfamiliar with the project enough background to understand the decision without reading the full specification.

-A table of cross-references to other ADRs that interact with this decision. Each entry includes a link to the related ADR, its title, and a brief description of the relationship. This is always the second-to-last section.
+#### Decision

-### Acceptance
+States the architectural choice that was made, written in declarative form (e.g., "CleverAgents adopts X"). This is the core commitment of the ADR — a concise, authoritative statement of what was decided. Implementation details belong in Design; this section focuses on the *what*, not the *how*.

-Records the governance process for the ADR. This is always the last section.
+#### Design

-| Section | Purpose |
-|---------|---------|
-| **Votes For** | Table of voters who voted in favor, with optional comments and a total count. |
-| **Votes Against** | Table of voters who voted against, with optional comments and a total count. |
-| **Abstentions** | Table of voters who abstained, with optional comments and a total count. |
+Provides the structural details that realize the decision: components, interfaces, data models, patterns, protocols, and interaction flows. This is typically the longest section of an ADR and may include sub-headings, diagrams, and code-level specifics. The Design section should give an implementer enough information to build the feature correctly without inventing architectural choices on their own.
+
+#### Constraints
+
+Lists the explicit rules and restrictions the decision imposes on the codebase. Constraints are enforceable invariants — statements like "module X must never import from module Y" or "all domain models must use Pydantic strict mode." They serve as guardrails that CI checks, linters, and code review can verify mechanically.
+
+#### Consequences
+
+Documents the outcomes of the decision, organized into three categories: **Positive** (benefits gained), **Negative** (trade-offs accepted), and **Risks** (potential future problems). Honest accounting of trade-offs is essential — an ADR that lists only positive consequences is incomplete. This section helps future readers understand whether the decision's assumptions still hold.
+
+#### Alternatives Considered
+
+Describes other options that were evaluated and explains why they were not chosen. Each alternative should include enough detail for a reader to understand the rejected approach and the reasoning behind the rejection. When the decision is directly prescribed by the specification with no practical alternatives, this section may read "None — specification-driven requirement."
+
+#### Compliance
+
+Specifies how adherence to the decision is verified in practice. This includes CI checks, linting rules, architecture tests, code review expectations, and any other enforcement mechanisms. A decision without a compliance strategy is aspirational rather than architectural — this section ensures every ADR is backed by concrete verification.
+
+#### Related ADRs
+
+A table of cross-references to other ADRs that interact with this decision. Each entry includes a link to the related ADR, its title, and a brief description of the relationship (e.g., "Provides the persistence layer used by this system" or "Defines the validation strategy referenced in the Constraints section"). Cross-references are maintained in both directions — when a new ADR references an existing one, the existing ADR's Related ADRs table is updated as well. This is always the second-to-last section.
+
+#### Acceptance
+
+Records the governance process for the ADR. Contains three sub-tables — **Votes For**, **Votes Against**, and **Abstentions** — each listing the voter's identity, an optional comment, and a total count. The Acceptance section is populated during the review process: votes are cast, recorded, and once the outcome is determined the ADR's status is updated to `Accepted` (or remains `Proposed` if rejected). This is always the last section of every ADR.

 ## ADR Inventory