# Solution Design / Spec

Use for engineering, architecture, DevOps, integration, migration, or any
non-product feature work where a direction has been chosen but not yet built.

Use the minimum-sufficient version: the smallest form that fully preserves the
understanding, and no smaller. Drop sections that add nothing for this particular
problem — an empty section is noise.

## Template

```markdown
# Title

## Problem

## Context

## Goals

## Non-goals

## Current state

## Options considered

## Recommended approach

## Rationale

## Decisions and rejected alternatives

## Risks and mitigations

## Validation

## Documentation impact

## Open questions
```

## Notes on key sections

**Options considered vs Decisions.** Keep these two sections doing different jobs
so the rejected options aren't written twice. *Options considered* is the
landscape *before* the choice — the candidates and their trade-offs as they
stood. *Decisions and rejected alternatives* is the outcome *after* the choice —
what was picked and why each alternative was rejected. Frame in the first, judge
in the second.

**Decisions and rejected alternatives** is the highest-value section. Capture:

- accepted decisions and the reason behind each
- rejected alternatives and *why* they were rejected
- subtle constraints and important defaults
- sequencing decisions
- assumptions future agents must not silently re-derive

Do not turn this section into an ADR dump. Keep decisions that are local to this
work here; promote a decision to its own ADR (`artifacts/adr.md`) only when it is
durable, surprising, the result of a real trade-off, and matters beyond the scope
of this work — cross-cutting, relevant to readers elsewhere (see the scope test
in `artifacts/adr.md`).

**Validation** describes how we will know the implementation is correct — tests,
checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.