// Use when documenting architecture decisions as ADRs, evaluating trade-offs between alternatives, or managing the lifecycle of existing decisions. Covers ADR template, status transitions, consequence analysis, and quality criteria.
| name | architecture-decisions |
| description | Use when documenting architecture decisions as ADRs, evaluating trade-offs between alternatives, or managing the lifecycle of existing decisions. Covers ADR template, status transitions, consequence analysis, and quality criteria. |
Architecture Decision Records (ADRs) are lightweight documents that capture architectural decisions together with their context, alternatives considered, and consequences. They are the institutional memory of the architecture.
Purpose: An ADR answers the question: "Why does the architecture look the way it does?" Future readers — including future you — should be able to understand any structural decision without needing to ask the original author.
Core rule: One ADR per decision. A decision is a single, clear choice with trade-offs.
# ADR-{NNN}: {Short Title}
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
**Date:** {YYYY-MM-DD}
## Context
{Describe the situation and the forces that led to this decision. What problem were you solving? What constraints were in play? Why was a decision needed at all?}
## Decision
{State the decision clearly and directly. Start with "We will..." or "We have decided to...". One paragraph, maximum. Avoid explaining why here — that belongs in Context and Alternatives.}
## Consequences
**Positive:**
- {benefit 1}
- {benefit 2}
**Negative / trade-offs:**
- {trade-off 1}
- {trade-off 2}
**Neutral:**
- {change that is neither good nor bad but worth noting}
## Alternatives Rejected
| Alternative | Reason rejected |
|---|---|
| {option A} | {why not chosen — specific, not a strawman} |
| {option B} | {why not chosen — specific, not a strawman} |
# ADR-001: Apply CQRS for Eligibility Check
**Status:** Accepted
**Date:** 2026-05-01
## Context
The eligibility check feature has distinct read and write concerns. The command side modifies eligibility state and raises the `EligibilityChecked` domain event. The query side needs to return a lightweight `EligibilityResult` read model optimised for display in the driver portal. Using a single model for both would force a compromise: either the domain model is polluted with display concerns, or the read model is burdened with invariant enforcement.
## Decision
We will apply simple CQRS: separate command handlers (mutate state, raise events) from query handlers (return read models). Both sides share the same relational database but use separate models. Command handlers write to the `eligibility` table via the domain aggregate. Query handlers read from an `eligibility_read` view or projection table.
## Consequences
**Positive:**
- Command and query models evolve independently — adding a display field does not touch the domain model
- Read models can be optimised (indexed, denormalised) without affecting domain logic
- Aligns with the event model produced in the Event Modeling session
**Negative / trade-offs:**
- Two code paths to maintain instead of one
- Slight increase in complexity for features that are simple reads/writes
- Developers must understand which side to modify when changing behaviour
**Neutral:**
- No separate database or event store required at this stage — keeping full CQRS as a future option if read volume grows
## Alternatives Rejected
| Alternative | Reason rejected |
|---|---|
| Single CRUD service (no CQRS) | Would mix mutation and query concerns in one model, forcing compromises in both directions as the feature grows |
| Full CQRS with separate stores | Over-engineering for current scale; no read replica needed yet |
adr-{NNN}-{slug}.md
Examples:
adr-001-cqrs-eligibility.mdadr-002-aggregate-boundary-eligibility.mdadr-003-event-sourcing-rejected.mdRules:
001, not 1Proposed → Accepted → Deprecated
→ Superseded by ADR-{NNN}
Linking rule: When ADR-002 supersedes ADR-001:
Superseded by ADR-002No ADR is ever deleted. The historical record of why a decision was made is as valuable as the decision itself.
Write an ADR for any decision that:
Do not write an ADR for:
Every ADR must demonstrate genuine trade-off analysis — not a decision with only upsides.
| Force | Question |
|---|---|
| Simplicity | Does this make the system easier to understand and change? |
| Consistency | Does this fit the patterns already established in this codebase? |
| Performance | Does this meet the performance requirements without over-engineering? |
| Evolvability | Does this make future changes easier or harder? |
| Team capability | Can the current team maintain this without a steep learning curve? |
| Force | Option A | Option B | Weight |
|---|---|---|---|
| Simplicity | High | Low | High |
| Consistency | High | Medium | Medium |
| Performance | Medium | High | Low |
| Evolvability | High | High | High |
| Team capability | High | Low | High |
| → Score | 4.2 | 2.8 | |
Use this table in the Context section when the decision is genuinely hard. Skip it for obvious decisions.
Before writing the final ADR, verify:
Proposed when drafting, Accepted when ratifiedInstall the full eleven-workflow skraft SDLC pipeline (discover → discuss → design → distill → deliver, each with an automated reviewer) into the current repo in one pass. Use when the user wants an end-to-end agent pipeline driven by a single issue label, or types /install-skraft-pipeline.
Use when reviewing DISTILL artefacts (Gherkin scenarios, test plans, implementation plans) for quality, completeness, and alignment. Contains the gate definitions and scoring rubric for the acceptance-designer-reviewer lenses.
Use when selecting architecture patterns for a new feature, performing Event Modeling, defining bounded contexts, choosing DDD tactical patterns, evaluating pattern fitness, or understanding how patterns compose. Covers Event Modeling methodology, DDD strategic design, DDD tactical patterns, Clean Architecture, CQRS, and Event Sourcing.
Use when reviewing DESIGN artefacts (event models, ADRs, component diagrams, context maps, interface contracts) for quality, DDD compliance, and architectural correctness. Contains gate definitions and scoring rubric for the solution-architect-reviewer lenses.
Use when writing, reviewing, or structuring BDD scenarios in Gherkin format. Covers Given/When/Then conventions, scenario outline patterns, background usage, tag strategies, and domain language alignment. Load before any Gherkin authoring.
Use when deciding what to test at each Clean Architecture layer (Domain, Application, Infrastructure, API, Architecture), selecting test doubles per boundary, or enforcing layer boundaries through architecture tests. Language-agnostic principles with .NET, Java, Python, TypeScript examples.