// 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 | Rejected | 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.md (slug names the topic; verdict lives in the Status: field — Accepted or Rejected)Rules:
001, not 1-rejected, -accepted, -deprecated, -superseded. The verdict lives in Status:.Proposed → Accepted → Deprecated
↘ Rejected → 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.
The Proposed → Accepted | Rejected transition is owned by a human, not the agent. The ratification channel is supplied by the execution context (the orchestrating workflow when running in an agentic pipeline, or an in-terminal prompt when running locally) — this skill does not prescribe the channel.
Both transitions are committed: the Proposed revision AND the final Accepted / Rejected revision land in git history. The trail of "we paused here for a human" is part of the architectural record.
A Rejected ADR documents that an option was seriously evaluated and the team decided NOT to adopt it. The ADR exists so the same debate is not re-opened in six months without new evidence.
adr-NNN-event-sourcing.md, NEVER adr-NNN-event-sourcing-rejected.md. The verdict lives in Status:, not in the filename.Rejected status means.Rejected ADR is written ONLY when a story or measurable force in the current batch raised the question (see G9 traceability). A Rejected ADR with no triggering story is a non-decision artefact and is forbidden.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 ratifiedUse when reviewing DESIGN artefacts (event models, ADRs, component diagrams, context maps, interface contracts) for quality, DDD compliance, architectural correctness, and prohibition of negative or baseline-restating ADRs. Contains gate definitions and scoring rubric for the solution-architect-reviewer lenses.
Use when designing test coverage matrices, assigning tests to Clean Architecture layers, planning the outside-in implementation order, or applying the Walking Skeleton strategy. Ensures every behaviour is tested at the right level with no redundancy. Load after writing Gherkin scenarios.
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 DISCOVER artefacts (triage reports, sprint proposals) for completeness, prioritization quality, and duplicate handling. Contains gate definitions G1-G6 and scoring rubric for the backlog-discoverer-reviewer lenses.
Install 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.
iOS 26 Liquid Glass design system — dynamic glass material with blur, reflection, and interactive morphing for SwiftUI, UIKit, and WidgetKit.