# Spec / TRD format

Use for a technical design that needs a problem statement, architecture, contract, and risk review.

## Great instance

- Opens with the problem and non-goals.
- Shows architecture or flow as a Mermaid diagram.
- Puts interface examples in fenced code blocks.
- Names risks with mitigations and tests.

## Cut

- Implementation diary.
- Diagrams with no decision value.
- Contracts described only in prose.

## Skeleton

````markdown
# TRD: <system or change>

## Problem
<user or system problem, constraints, non-goals>

## Design
```mermaid
flowchart LR
  Client --> API --> Store
```

## Contract
```ts
export interface RequestShape {
  field: string;
}
```

## Risks
| Risk | Mitigation | Test |
| --- | --- | --- |
````

## Section prompts

- Keep the contract copyable.
- Use one diagram to explain structure or sequence.
- Put open questions in risks unless they block the design.
- Tie each risk to a gate or manual check.

## Renderer moves

Catalog: ../building-artifacts.md#what-each-file-type-becomes - md doc reader sections; mermaid architecture; anchored code blocks.