# Design doc / RFC format

Use when an engineer proposes a non-trivial technical change and needs reviewers to pressure-test the approach
before implementation.

## Great instance

- Frames the problem and constraints before any solution, so reviewers judge the design against the real goal.
- Presents one recommended design, then the alternatives it beat and why.
- Is honest about risks, tradeoffs, and what could go wrong.
- Makes the migration/rollout concrete enough to critique.

## Cut

- A solution with no stated problem or constraints.
- Every alternative the author ever considered — keep the 2-3 that a reviewer would actually raise.
- Implementation minutiae that belong in the PR, not the design.

## Skeleton

```markdown
# Design: <change>

## Context and problem
<what exists today, what's wrong, and the constraints any solution must respect>

## Goals and non-goals
- Goal: <what this design must achieve>
- Non-goal: <explicitly out of scope>

## Proposed design
<the recommended approach; a Mermaid diagram for the architecture or flow>

## Alternatives considered
| Option | Why not |
| --- | --- |
| <alt> | <the tradeoff that ruled it out> |

## Risks and tradeoffs
- <risk>: <mitigation>

## Rollout and migration
<phasing, backfill, flags, and the back-out plan>

## Open questions
- <unresolved decision, and who owns it>
```

## Section prompts

- Put the architecture or request flow in a Mermaid fence — it becomes a commentable region reviewers can pin.
- Give each alternative its own table row so a reviewer can challenge exactly one.
- State the back-out plan; reviewers trust designs that can be undone.

## Renderer moves

Catalog: ../building-artifacts.md#what-each-file-type-becomes - md doc reader sections; Mermaid architecture region + alternatives table anchors.