# 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 smallest version that preserves the useful thinking. 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

**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. Promote a decision to its own ADR
(`artifacts/adr.md`) only when it is durable, surprising, and the result of a
real trade-off.

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