# Brief to page brief

Version: 1.2
Updated: 2026-07-17

Purpose: turn a loose topic into a page where every section earns its place.

Output: a page sequence, evidence plan, interaction contract, and release test.

## Use when

A note, spoken request, or broad topic needs to become one coherent page rather than a pile of sections.

## Quick start

1. Write the reader promise and truth boundary before proposing sections.
2. Give each section one reader question, one job, and one proof point.
3. Remove repeated jobs, then define the next action and release conditions.

If you cannot complete the reader promise or truth boundary, stop there. More layout will not repair an unclear page.

## 1. Reader promise

- Primary reader:
- What they already know:
- Question or tension that brought them here:
- Useful outcome after reading:
- Common cost or confusion the page removes:

> After reading, [reader] can [useful outcome] without [common cost or confusion].

## 2. Truth and boundaries

| Type | Record |
|---|---|
| Facts the page may claim |  |
| Source or first-hand evidence |  |
| Claims requiring verification |  |
| Public-safety or privacy boundary |  |
| Explicitly out of scope |  |
| Existing page this must not duplicate |  |

## 3. Choose one primary shape

- [ ] Explainer — leave a mental model and clear definition.
- [ ] Playbook — leave steps, decisions, evidence, and stop conditions.
- [ ] Comparison — leave trade-offs and a decision rule.
- [ ] Field note — leave one observation and the decision it changed.
- [ ] Template — leave a copy-usable structure with guidance.

Why this shape fits the reader promise:

## 4. Page sequence

Do not start with a fixed number of sections. Add a row only when it answers a different reader question.

| Order | Reader question | Section job | Main point | Proof | Visual or interaction | Next destination |
|---|---|---|---|---|---|---|
| 1 | Why should I continue? | Orient |  |  |  |  |
| 2 |  | Differentiate |  |  |  |  |
| 3 |  | Explain |  |  |  |  |
| 4 | How do I use this? | Apply |  |  |  |  |
| 5 | What next? | Extend |  |  |  |  |

Cut a row when its job or proof duplicates another row.

## 5. Visual and interaction contract

- Visual thesis in one sentence:
- What a diagram, table, or image explains better than prose:
- Alt-text meaning:
- Small-screen reading order:
- Behaviour without animation:
- Primary action and expected result:
- Secondary action and expected result:
- Required states: default / hover / focus / active / disabled / error / success
- Touch and keyboard expectations:

## 6. Connected surfaces

- Backward link—idea this builds on:
- Sideways link—related idea:
- Forward link—next useful question:
- Metadata and canonical owner:
- Structured data:
- Navigation and internal-link locations:
- Sitemap, feed, search, or machine-readable surfaces:
- Downloadable or generated artifacts:

## 7. Release test

> At [viewports/environments], [reader] can [primary outcome]. The page preserves [invariant], and [evidence] proves the released artifact matches the brief.

- [ ] Every visible claim has a source or is clearly first-hand.
- [ ] No section repeats another section’s job.
- [ ] The page remains understandable without animation.
- [ ] Mobile preserves the intended reading order.
- [ ] Keyboard focus, headings, links, and tap targets are usable.
- [ ] Metadata and structured surfaces match visible content.
- [ ] Preview and production are inspected independently.

## Worked example

**Topic:** Why to verify live output before editing a local checkout.

**Reader promise:** After reading, an operator can identify which source owns a live page without trusting the nearest folder.

**Shape:** Playbook, because the useful outcome is a repeatable sequence with stop conditions.

| Order | Reader question | Section job | Main point | Proof | Visual or interaction | Next destination |
|---|---|---|---|---|---|---|
| 1 | Why is the nearest folder risky? | Orient | local proximity is not ownership | one divergence example | source-to-deploy diagram | start the check |
| 2 | What must agree? | Explain | live response, deploy, revision, source | four-point checklist | compact table | run commands |
| 3 | What can HTTP 200 not prove? | Differentiate | transport is not content identity | hash mismatch example | comparison | inspect ownership |
| 4 | When should I stop? | Apply | ambiguity must pause edits | stop-condition list | callout | use checklist |

**Release test:** At mobile and desktop widths, the reader can find the four ownership checks and the stop conditions; every command is read-only and the linked download matches its description.

## Next seed

- Strongest useful question left unanswered:
- Why it deserves a separate page:
- Reader promise for that page: