product-description

# Product description repo

A product description treats the product as a large state chart the user moves through with input. The repo describes that state chart feature by feature, in plain language, from the user's point of view, with the same skeleton for every document so that gaps and inconsistencies show up by comparison. Documents are drafted from the source code and its tests, then verified by hand against the running product, and everything that looks like a defect is collected into one triage file.

The files under `references/`:

| File | What it is |

| --- | --- |

| `product-kinds.md` | How to map the template onto a canvas editor, a web app, a CLI, or a chat product. Read in Phase 0. |

| `README-template.md`, `goal-template.md`, `glossary-guide.md` | Skeletons for the three files that steer the whole build. |

| `document-template.md` | The eight-section skeleton every feature document follows. |

| `verification-template.md`, `bug-triage-template.md` | Skeletons for the checking half. |

| `check-links.py` | Link and anchor checker for the consistency pass. `python3 check-links.py {repo}`. |

## Outputs

## Phase 0: scope

Settle these before writing a file. Ask only for what you cannot infer from the conversation or the source repo; record the answers in the README's "Scope decisions" section.

1. **Product and surface.** What exactly is being described: which app, which route, role, or configuration, with what customization (usually "the defaults, nothing customized"). One surface per repo.

2. **Source of truth.** The path to the source repo (read-only reference) and the commit. Every document footer cites `git rev-parse --short HEAD` of that repo.

3. **Where to run it.** The command and URL, binary, or account that brings up the surface for verification.

4. **Out of scope.** Name what is excluded and why, so later readers do not think it was forgotten.

5. **Where the repo goes.** A new directory of its own, outside this repository and never under the workspace's own folder; `git init`, first commit `Initial commit`. Where a change of this repository commissioned the program, its record links to it.

6. **The product's shape.** Read `references/product-kinds.md` and decide, once: the unit of interaction and the names of its five phases; the variant axis (modifiers, flags, roles); the fixed interrupt list; the cross-cutting concerns and their order. These go into the README's "Document template" section and the glossary before the pilot is written, and they do not change afterwards without revisiting every document.

Then do a reconnaissance pass over the source repo to find: where interaction state lives (state machines, reducers, controllers, route handlers, command definitions), where behavior tests are (the ones that read as executable specs of edge cases), where the UI is, and where defaults and thresholds are defined (options, constants, config schemas). These go into the README's "Reference" section and goal.md's reading order.

## Phase 1: scaffold

Write, in this order, adapting the templates in `references/`:

1. **README.md** from `README-template.md`. The structure section is the plan: list every document you expect to write with a one-line gloss, grouped by how the user meets the feature (foundations, then the areas of the product, then cross-cutting concerns), never by package or module. The coverage table lists every document as `not started`. Getting the structure right up front is most of the planning; expect to revise it as you learn, and update the table whenever you do.

2. **glossary.md** from `glossary-guide.md`. Start with the terms the foundations will need and the interrupt words from Phase 0; grow it as documents demand new words. A term used in a document that is not in the glossary is a consistency bug.

3. **goal.md** from `goal-template.md`. This is the prompt that drives all drafting. Its "Things already established" section is empty at first and fills in as the foundations are written.

4. **AGENTS.md** with the one-line contents shown under Outputs. Do not leave AGENTS.md empty; it is what a fresh session reads first.

Commit: `docs: add README, glossary, goal`.

## Phase 2: pilot, foundations, the hard part

Do these yourself, in sequence, not in parallel. They fix the template, tone, depth, and vocabulary that everything else copies.

1. **Pilot.** One small, self-contained feature with a real interaction in it (`product-kinds.md` names one per product kind). Write it on the full eight-section template (`document-template.md`). Iterate on it until it is right; every later document copies it. A small feature done properly runs around 150–200 lines, with every phase narrated, every variant and interrupt cell filled, and the cross-cutting list walked in full; if a section is thin, the feature has not been read closely enough yet.

2. **Foundations.** The documents everything else links to: the input or invocation model (events, thresholds, what cancels, completes, and interrupts), the core object or data model, the mode, tool, or navigation model, the viewport or session model. These *own* the facts other documents link to instead of restating. As each is written, add its load-bearing facts (numbers, defaults, rules) to goal.md's "Things already established" so no later document re-derives or contradicts them.

3. **The hardest area.** The bulk of the experience (the selection tool, the main editor, the `build` command, the composer plus the streaming response). Read all of its state handling before writing any of its documents, because the states hand off to each other and the documents must agree on where one ends and the next begins. Decide which document owns each state and write that down in goal.md.

Commit after each document or coherent group: `docs: add {path}`.

Once the exemplars exist, the remaining documents are independent. Draft them one after another, one document or small cluster at a time. Hold each draft to this brief, whether you write it or, on the owner's yes, a fresh agent does through the harness's delegation, one agent at a time, as the program's drafter rather than a fresh agent of a change, since the program opens no record in this repository and no record cites what it drafts:

> Read `goal.md`, `README.md`, `glossary.md`, `{pilot}`, and `{the foundation document this feature depends on}`. Write `{area}/{feature}.md` on the same skeleton, at the same depth. Use the glossary's words; if you need a term it lacks, add it to `glossary.md` in the right section with a full definition rather than coining a synonym. Do not edit any other existing document. Do not modify the source repo. End with "## Open questions and verification" and the footer. Report what you could not determine from code and tests.

Review every result yourself before accepting it. Check: glossary words used correctly, established facts not contradicted, relative links resolve, footer present, interrupt table complete (every row, even if the answer is "no effect"), suspected bugs stated plainly in "Open questions" rather than smoothed over.

Update the coverage table to `drafted` as each lands. Commit in groups: `docs: add {paths}`.

## Phase 4: consistency pass

Over the whole set:

- Same term for the same thing everywhere; every term of art defined in the glossary; glossary definitions agree with the documents.

- No two documents describe the same behavior differently. Where two documents touch, one owns the behavior and the other links.

- Every relative link and heading anchor resolves: `python3 {skill dir}/references/check-links.py {repo}` (exit 1 and a list of `file:line: missing file|anchor` if not).

- Every document has the footer and an "Open questions and verification" section.

- The interrupt table has the same rows in the same order in every document; the cross-cutting concerns appear in the same order.

- The README structure and coverage table match the files on disk exactly.

Commit: `docs: revise the set after the consistency review`. Then go back through the documents whose open questions were thinnest and deepen them; expect a second revision pass on a handful of documents.

## Phase 5: verification checklists

Drafting reads the code; verification watches the product. From `verification-template.md`:

- `verification/README.md`: how to bring up the surface, confirm the commit, run a pass, record results, file failures, and when a document moves from `drafted` to `verified`.

- One checklist file per cluster of documents, one table per document, one row per observable claim: stable ID (`AREA-NN`), priority (P1 established fact or suspected bug, P2 ordinary claim, P3 a number, color, or timing), what it needs (device, role, network condition), the claim with a link to the section, setup, numbered steps, expected result, Result column (`—` until run). Claims that cannot be checked by hand go under "Not checkable by hand".

If you can drive the product (browser tools, a console handle on the app, a shell for a CLI, a test harness; the verify step's pages carry the methods for a browser and a shell), run a first pass yourself on what can be observed that way, record the results in the Result columns, and say plainly in `verification/README.md` what that pass did and did not cover (for example: a scripted pass checks output, exit codes, and stored state but not what was shown on screen or how long it took to appear). Do not mark a document `verified` on the strength of an automated pass alone. A failed item is not automatically a product bug; sometimes the document is wrong, and the Status line says which. A single claim that needs proof of its own is the verify step's to prove.

## Phase 6: bug triage

From `bug-triage-template.md`: collect every suspected defect from every document's body and open questions, merge duplicates (the same root cause raised by many documents is one entry with many "Raised by" links), and write each up with where the user meets it, what happens vs. what was expected, reproduction steps, the cause in the code with file and line, a severity, and the decision the product team needs (`fix` or `product call`). Summary table at the top sorted by severity. Entries confirmed by a verification pass carry a **Status** line.

**Filing upstream is a separate, outward-facing step.** Offer it; do not do it unasked, and file only on the owner's authorization. If the user wants the entries filed as issues, confirm the repo and the format first, file them, then add an Issue line to each entry and a link column to the summary table (`docs: revise bug-triage.md with links to the filed issues`).

## Resuming and extending an existing repo

A later session, or a request to add a feature that was out of scope, starts here rather than at Phase 0.

1. Read `AGENTS.md`, `README.md` (structure, coverage table, scope decisions), `goal.md` (established facts), and `glossary.md`. Read the pilot to recalibrate depth.

2. Confirm the source repo's commit. If it has moved, decide with the user whether new documents cite the new commit (and say so in their footer) or the repo pins the old one. Do not silently mix.

3. To add a document: add it to the README structure and coverage table first, write it, add its checklist table to the right `verification/` file (new ID prefix, numbered from 01), add any new triage entries to `bug-triage.md` with the next `B-NN`, and commit each step: `docs: add {path}`, `docs: add the {name} checklist ({PREFIX}-01 to {PREFIX}-NN) to verification/{cluster}.md`, `docs: add B-NN to B-MM to bug-triage.md from the {name} work`.

4. To revise a document after a verification pass: change the document, update the checklist row's Result and note, update the triage entry's Status, and commit as `docs: revise {path}`.

5. Never renumber checklist IDs or triage IDs once a pass or an issue has used them.

## Writing rules (carry into goal.md verbatim or adapted)

- Describe the experience, not the code. "The form stays disabled until the server answers", not "the mutation sets isPending". "The file is written only after every check passes", not "validate() runs before write()".

- Technical detail only in `> Technical note:` block quotes, and only when the mechanism changes what the user would expect.

- Sentence case for headings. Direct, concrete, no hedging, no marketing.

- Surprising behavior is stated plainly, with the reason if the code or a comment gives one. If it looks like a bug, say so in "Open questions".

- Variants and interrupts go in tables, split by phase ("at the start" / "during"). Every cell filled, even with "no effect".

- Cross-reference with relative links instead of repeating. The foundation documents own thresholds and definitions.

- One Mermaid `stateDiagram-v2` per interaction, limited to the states the user passes through. When a chart outgrows a readable Mermaid block, draw it with `diagram-design` (extra) into the description repo and link it from the document.

- Footer: `## Open questions and verification`, a bullet list, then `Verified against {repo} commit \`{sha}\``.

- Commits: `docs: add {path}` / `docs: revise {path}`. Follow whatever the user's repo does about AI attribution in commit messages.

- Never modify the source repo. It is read-only reference material.

- When a behavior cannot be determined from code and tests, write what can be determined, put the rest in "Open questions", move on. Do not guess, do not block.

## What never changes, whatever the product

The outside-in stance; one skeleton for every document; the interrupt list asked of every feature in the same order; a glossary that owns the words; foundations written first so they own the numbers; a pilot that sets the depth; drafting from code and tests, then verifying against the running product, then triaging what looks wrong. `product-kinds.md` is about what to rename; this list is what not to.

# README template

Placeholders are written `{like this}` and are usually an instruction or a menu of examples; replace every one with real prose (angle-bracket placeholders are not used because GitHub renders them as HTML and they vanish). Keep the section order. The "Structure" block and the "Coverage" table are the plan; keep them exact mirrors of the files on disk.

---

# {product} product description

A written description of the user experience of {product}: what the user sees, what they can do, and exactly what happens when they do it.

## Purpose

{product} is, from the user's point of view, a large state chart. The user moves through it with {the product's inputs: pointer events, drags, clicks, modifier keys, scrolls, keyboard shortcuts / taps and swipes / commands and flags / form submissions}. Most of that behavior is defined implicitly, spread across {where it lives in the code: state machines, reducers, handlers, tests, the UI}. There is no single place that says, in plain language, "when the user does X, this is what happens, and this is what happens if they do Y halfway through."

This project is that place. It describes the full experience a user has on {the surface being described: a specific route of the app / the default installation / the production site with a fresh account}, in {the default configuration, with nothing customized}.

The documents are for people who need to understand or change the product: designers, engineers, writers, testers, and anyone evaluating whether a behavior is intentional. They are written from the outside in. They describe the experience, not the implementation.

### What this is not

- Not API documentation. {Say where that lives.}

- Not organized by package. {The product's packages or modules} are not described separately. A single behavior is described once, wherever the user encounters it.

- Not a technical design document. Where a technical detail is critical to understanding the experience, it appears in a block quote labeled `Technical note:` and nowhere else.

## Conventions

- Describe the experience, not the code. "{an experiential sentence}" rather than "{the same thing said about the code}".

- Technical detail goes in block quotes, prefixed with `Technical note:`. Use it only when the mechanism changes what the user would expect.

- Use sentence case for headings.

- Name the vocabulary consistently. The [glossary](glossary.md) is the source of truth for terms like {five or six of the product's load-bearing terms}.

- Every document ends with the commit of {the source repo} it was verified against and a list of open questions.

- When a behavior is surprising, say so and say why it is that way if the reason is known. Do not smooth it over.

## The work to be done

Each document describes one feature. Features are large things ({example of a big one}) or small things ({example of a tiny one}), but each is described in full, including its edge cases and its interactions with other features.

### Document template

Every feature document follows the same skeleton so that documents are comparable and nothing is skipped.

1. **Summary.** One paragraph describing the feature abstractly. For example: "{one-sentence summary of the pilot feature}."

2. **The simple case.** The common path in prose.

3. **The interaction, event by event.** The five phases of {the product's unit of interaction: a gesture / a page or form lifecycle / an invocation / a turn}: {name them in the product's words: starting; ending at once; becoming extended; while extended; finishing}. What starts it and what is captured, what happens if it ends at once, what is decided the moment it becomes extended, what updates live, and what is committed at the end. Include a small state diagram (Mermaid `stateDiagram-v2`) of the states the user passes through.

4. **Modifiers.** A table of {Shift, Alt/Option, Ctrl/Cmd, and Space / the product's variant axis: roles, record states, flags, modes}, and what each one does when set at the start and when changed *during* the interaction.

5. **Cancel and interrupt.** The same checklist in every document:

- {The user's explicit abort: Escape, Stop, Ctrl+C, a Cancel button}

- {The user doing something else mid-way: switching tools, modes, tabs, or conversations; navigating away; sending another message}

- {The events the product treats as a clean "complete": a menu opening, undo or redo, a submit from elsewhere}

- {The environment failing: window loses focus, network lost, request fails or times out, session expires}

- {The page or process going away: reload, tab closed, terminal closed, app backgrounded}

- {Something else changing the target: deleted, locked, edited by another user or tab, changed on disk}

- {The input channel changing: a second input device, autofill, a pipe closing, touch cancel} {Rewrite this list for the product, drawing on the five families in the skill's product-kinds.md: the user's explicit abort, the user doing something else mid-way, the environment failing, something else changing the target, the input channel changing. It must be identical, and in the same order, in every document.}

6. **Interactions with other systems.** {The product's cross-cutting concerns, in a fixed order: permissions, history or undo, containers or parents, locked or readonly state, offline, collaboration or multi-device, notifications, configuration and preferences.}

7. **Edge cases.** Anything a user could notice that is not covered above.

8. **Open questions and verification.** The {source repo} commit the document was verified against, and any behavior that could not be confirmed.

Item 5 matters most. Asking the same interrupt questions of every feature is how gaps and inconsistencies are found.

### Method

For each document:

1. Read {where the interaction state lives} and the relevant {domain objects}.

2. Read the matching tests in {test directory}. Files like {list the ones that read as executable specifications} are close to executable specifications of the edge cases.

3. Draft the document.

4. Try anything ambiguous {in the running product: URL, binary, or account}. Tests settle "what happens"; the running product settles how it feels, what is visible while the interaction is in progress, and what the timing is like.

5. Record the commit verified against.

### Verification

Drafting reads the code; verification watches the product. The `verification/` directory holds one checklist per cluster of documents, each item a single observable claim with setup, steps, expected result, a priority, and the device it needs. A tester runs them {on the surface}, records `pass`, `fail`, or `blocked` in the Result column, and files every failure in `bug-triage.md` with the item's ID. A document moves from `drafted` to `verified` in the coverage table only when every P1 and P2 item for it has passed or been filed.

`bug-triage.md` is the other half: every behavior the documents flagged as a likely defect, deduplicated, with reproduction steps, the reason in the code, a severity, and the decision the product team needs to make. Entries confirmed {in the running product} carry a Status line.

### Order of work

1. **Pilot: {the pilot feature}.** Small and self-contained. Used to settle the template, tone, and depth.

2. **Foundations: {the input model / the core model}.** Everything else refers to it.

3. **{The hardest area}.** The bulk of the experience and the hardest part. Written third so the template is already proven.

4. **Everything else.** Once the template and two exemplars exist, the remaining documents can be drafted one after another, followed by a consistency pass and a verification pass across the whole set.

Progress is tracked in the [coverage table](#coverage) below.

### Scope decisions

- **{Excluded thing}.** {Why, and whether it gets a document later.}

- **{Concern described inside each document rather than separately}.** {Why: a separate document would drift.}

- **{Concern described once in a cross-cutting document rather than in every feature}.** {Why.}

- **Interaction shape.** The unit of interaction is {a gesture / a form lifecycle / an invocation / a turn} and its phases are {the five names}. The interrupt list and the order of cross-cutting concerns are fixed as written in the document template above.

- **Numbered rules.** These are prose documents, not numbered specifications. Stable heading anchors are enough for cross-references.

## Structure

```

README.md this file

goal.md the standing instructions for whoever drafts

AGENTS.md the entry point for agents: read README.md, then goal.md

glossary.md shared vocabulary

bug-triage.md suspected defects collected from every document, with repro steps and decisions needed

verification/

README.md how to run a hand-verification pass and record results

{cluster}.md checklists for {area}/ and {area}/

...

foundations/

{name}.md {one-line gloss, wrapping to a second indented line if needed}

...

{area}/

{feature}.md {gloss}

{sub-area}/

{feature}.md {gloss}

...

cross-cutting/

{concern}.md {gloss}

...

```

## Coverage

Status is one of `not started`, `drafted`, or `verified`.

| Document | Status |

| --- | --- |

| glossary.md | not started |

| bug-triage.md | not started |

| verification/ ({n} checklists) | not started |

| foundations/{name}.md | not started |

| ... | not started |

## Reference

The source of truth is {the source repo} at `{path or URL}`. The relevant locations are:

- `{path}`: {the surface this project describes}

- `{path}`: {where interaction state lives}

- `{path}`: {the domain objects}

- `{path}`: {the UI}

- `{path}`: {behavioral tests}

- `{path}`: {subsystems that shape the experience: hit testing, validation, scheduling, caching, sync, etc.}

# Bug triage template

`bug-triage.md` collects every suspected defect raised anywhere in the documents (bodies and "Open questions" sections), deduplicated by root cause, written up so a product team can decide each one without re-reading the documents. Expect the open questions across the set to collapse to roughly half as many entries once merged.

## Building it

1. Grep every document for "Open questions", "suspected", "looks like a bug", "may be worth treating as a bug", "inconsistent", "not handled", and read each "Open questions and verification" section in full.

2. Sort the raised items into *unconfirmed* (the document could not tell from the code; stays in the document's open questions) and *looks wrong* (the code does something a user would not expect; becomes a triage entry).

3. Merge by root cause. Fourteen documents saying "a reload mid-way loses the draft" is one entry with fourteen "Raised by" links. Two documents describing different symptoms of one missing handler is one entry.

4. For each entry, go back to the code and pin the cause to a file and line range. An entry without a cause is an observation, not a triage item.

5. Assign severity and the decision needed. Sort the summary table by severity, then by area.

6. Write the Summary paragraph last: how many were raised, how many remain after merging, how many are high, what the largest clusters are.

## Shape

```

# Bug triage

A consolidated list of the defects and inconsistencies that the feature documents raised in their "Open questions and verification" sections and in their bodies. Each entry is read from {the source repo} and tests; the {n} that have been confirmed {in the running product} carry a **Status** line. {If filed: Every entry was filed as an issue on the source repo on the date (#NNNN–#NNNN); the Issue lines link them.} The list exists so the product team can decide, item by item, whether to fix, to document as intended, or to leave.

## Summary

{One paragraph: counts, clusters, what the high ones have in common.}

| ID | Title | Severity | Area | Decision needed | Issue |

| --- | --- | --- | --- | --- | --- |

| B-01 | {Title as a statement of the wrong behavior} | high | {area} | fix | {link or —} |

| ... | | | | | |

## High

### B-01: {Title}

- **Where the user meets it:** {The situation, in user terms.}

- **What happens / what was expected:** {Both halves, plainly.}

- **Reproduce:** {Numbered or prose steps; name the device if one is needed.}

- **Why (from the code):** {File paths and line ranges; the missing handler, the wrong comparison, the order of operations.}

- **Severity:** `high` | `medium` | `low`. {One clause on why.}

- **Decision needed:** `fix` | `product call`. {What the fix would be, or what the call is.}

- **Raised by:** [{document}]({path}#open-questions-and-verification), [{document}]({path}#{anchor}), ...

- **Status:** {Only if a verification pass touched it: confirmed / not reproduced / document was wrong, on what date, by what means, with the checklist item IDs.}

- **Issue:** {Only if filed: [owner/repo#NNNN](url).}

## Medium

...

## Low

...

```

## Severity and decision

- **high**: loses work, leaves the user in a state they cannot get out of, makes one common action do two things at once, silently does something different from what was confirmed, or affects every feature (a missing global handler).

- **medium**: wrong but recoverable; an undo step missing; an inconsistency between two features that should match; a wrong result in an uncommon path.

- **low**: cosmetic, a copy slip, a quirk only an expert would notice. Group tiny slips into one entry ("Small copy and rendering slips") with a sub-list.

- **fix**: the expected behavior is obvious and the entry says what the fix is.

- **product call**: reasonable people could want either behavior; the entry states both and what each costs.

## Filing upstream

Outward-facing; do only when the user asks, after confirming the target repo and the issue format. One issue per entry, title from the table, body from the entry (omit the "Raised by" links unless the description repo is public), a label if the repo uses them. Then add the Issue line to each entry, the Issue column to the table, and the range to the intro paragraph. Commit as `docs: revise bug-triage.md with links to the filed issues ({owner}/{repo} #NNNN–#NNNN)`.

# Feature document template

Every feature document (a tool, a screen, a form, a command, an action, a kind of turn) uses all eight sections. Foundations, UI, and cross-cutting documents may drop sections that do not apply (a settings panel has no extended phase; a static page has no variants) but must still cover interrupt behavior wherever an interaction exists. The pilot document is the complete instance every other document copies. A small feature done properly runs around 150–200 lines; the hardest documents run 250–300.

Headings are sentence case. The H1 is "The {feature}" for tools, screens, and UI ("The invite form", "The toolbar", "The composer"), the bare noun or command for objects, actions, and commands ("Attachment", "Clipboard", "`init`"), and a descriptive phrase for cross-cutting concerns ("Unsaved changes", "Offline", "Configuration precedence").

Section 3's five subsections are the phases of the product's unit of interaction, decided once in Phase 0 (see `product-kinds.md`): **starting**, **ending at once**, **becoming extended**, **while extended**, and **finishing**. Rename the subsection headings to the product's own words for those phases (for a form: arrive / leave untouched / begin editing / while editing / submit; for a command: invoke / exit immediately / begin running / while running / finish; for a gesture: press / release without dragging / begin dragging / while dragging / release) and keep the same five slots in the same order in every document.

---

# The {feature}

## Summary

One paragraph, abstract: what the feature is and what it lets the user do. Then the concrete identity in one or two sentences: where it lives (which screen, menu, or command), how it is reached (a shortcut, a button, a route, a subcommand), what signals that it is active, and whether it is available in restricted states (readonly, a lesser role, offline, a pipe instead of a terminal).

## The simple case

The common path in prose, two to four short paragraphs. No variants, no edge cases. What the user does and what they see. Note whether the feature stays active afterwards or returns to a default, and where the user lands.

## The interaction, event by event

```mermaid

stateDiagram-v2

[*] --> idle

idle --> started : {what begins it}

started --> idle : {ends at once} (commit)

started --> idle : cancel, interrupt (discard)

started --> extended : {what makes it extended}

extended --> idle : {what finishes it} (commit)

extended --> idle : cancel (discard)

```

Only the states the user passes through, named in the product's words (`viewing`, `dirty`, `submitting`, `saved`; `parsing`, `running`, `done`, `failed`; `composing`, `waiting`, `streaming`, `complete`; `pointing`, `dragging`). Omit internal bookkeeping states. Label every transition with what triggers it and, in parentheses, what it commits or discards.

### {Starting}

What begins the interaction and what is decided at that instant: what is targeted and how the target is chosen, what is loaded, focused, or prefilled, what is validated before anything runs, what is captured or snapshotted so it can be restored. What changes visibly right away. Which variant, if set *at* the start, changes the outcome.

### {Ending at once}

The short path: the interaction ends before it becomes extended (a click without a drag, a page left untouched, `--help` or a usage error, an empty message). What, if anything, is committed or recorded; whether it can be undone; what the feature does next (stays active, returns to a default). Say explicitly when nothing is recorded; "nothing" is a claim the tester can check.

### {Becoming extended}

What crosses the line from the short path to the long one (a distance or time threshold, the first edit that makes the form dirty, the first side effect after which aborting is no longer free, the moment a message is committed to history). What is decided at that instant and fixed for the rest of the interaction (the anchor, the original values, the set of things that will be affected). What visual or output begins.

### {While extended}

What updates continuously and how the live result is computed in user terms (the thing follows the input by the offset it was grabbed at; validation runs on each keystroke but errors show on blur; progress is reported per file; the response streams token by token). What is cumulative and what is recomputed from scratch. What the user can still do meanwhile and what is disabled.

### {Finishing}

What is committed, as how many undo steps or which durable records or files. Side effects the user would notice (a notification is sent, a container takes its children with it, a lockfile is written, a draft is cleared). What the feature does next and where the user lands. The failure path, if the commit can fail: what is shown, what is kept, what is rolled back.

## Modifiers

| Modifier | Set at the start | Changed while extended |

| --- | --- | --- |

| {variant 1} | | |

| {variant 2} | | |

| {variant 3} | | |

| {variant 4} | | |

The rows are the product's variant axis from Phase 0 (modifier keys; the user's role and the record's state; flags, environment, and whether output is a terminal; the selected mode, attachments, and conversation state) and are the same rows in every document. Every cell filled, "No effect." where that is the answer. A sentence after the table on what changing a variant mid-interaction does (pressing or releasing a key, a role change taking effect, a flag that cannot change once running).

## Cancel and interrupt

| Event | {Before extended} | {While extended} |

| --- | --- | --- |

| {The user's explicit abort: Escape, Stop, Ctrl+C, Cancel} | | |

| {The user doing something else mid-way: switching tools, modes, tabs, or conversations; navigating; sending another message} | | |

| {The events the product treats as a clean "complete": a menu opening, undo or redo, a submit from elsewhere} | | |

| {The environment failing: window loses focus, network lost, request fails or times out, session expires, process killed} | | |

| {The page or process going away: reload, tab closed, terminal closed, app backgrounded} | | |

| {Something else changing the target: deleted, locked, moved, edited by another user or tab, changed on disk} | | |

| {The input channel changing: a second input device, autofill, a pipe closing, touch cancel} | | |

| {Any product-specific mode that changes what happens after the interaction} | | |

The rows are the product's interrupt list from Phase 0. They are the same rows in the same order in every document in the repo; rewrite them once for the product and then never vary them. The columns are the interaction's phases before and after it became extended. Every cell filled. Follow with a sentence or two on what happens *after* the interrupt (does the user stay in the feature or return to the default? is a draft kept? is partial work left on disk?) and a `> Technical note:` only if the mechanism produces a result the user would not expect.

## Interactions with other systems

One bold-led paragraph per cross-cutting concern, in the same order in every document: **{Permissions.}** **{History or undo.}** **{Containers or parents.}** **{Locked or readonly state.}** **{Offline and reconnection.}** **{Collaboration or multi-device.}** **{Notifications.}** **{Configuration and preferences.}** and whatever else the product has. The list and its order come from Phase 0. Include a concern even when the answer is "no interaction"; it is one line and it tells the reader the question was asked.

## Edge cases

A bullet list. Anything a user could notice that the sections above do not cover: overlapping or ambiguous targets, boundaries and limits (maximum size, count, length), nesting, the interaction started one way and finished another, repeated or double invocation, order-dependent outcomes, empty states, the very first and very last instance of something.

## Open questions and verification

- What was read from code but not confirmed by hand, one bullet each.

- Behavior that looks like a bug, stated as such: "may be worth treating as a bug rather than documenting."

- Assumptions the document rests on.

Verified against {source repo} commit `{short sha}`.

# Glossary guide

`glossary.md` is the source of truth for every term of art. A document that uses a word the glossary does not define, or uses it differently, has a consistency bug. Expect it to grow to dozens of terms over the course of the build.

## Shape

```

# Glossary

The vocabulary used across these documents. When a document uses one of these words, it means exactly this.

## {Section: the surface} e.g. The workspace / The terminal / The conversation

## {Section: the objects} e.g. Records / Documents / Messages / Files

## {Section: state} e.g. Selection and state

## {Section: modes} e.g. Tools / Modes / Roles

## {Section: the interaction} e.g. Gestures / Forms / Invocations / Turns

## {Section: input} e.g. Input

## {Section: gesture endings} e.g. Events that end or interrupt a gesture

## {Section: the document} e.g. Document / Project / Session

## {Section: the interface} e.g. Interface

## {Section: multi-user} e.g. Collaboration

```

Each term is one paragraph:

```

**Term.** Definition in one to four sentences. Concrete numbers where they exist (a draft is kept for 30 days; the default page size is 50). The rule that makes the term load-bearing ("Archiving a project also revokes every share link; the two cannot be separated"). A related term in *italics* on first mention.

```

## Rules

- Define the *state words* with care: selected, hovered, editing, focused, active, locked, hidden, dirty, saved. These are where documents disagree most.

- Define the *gesture-ending words* as a section of their own (cancel, complete, interrupt, and what dispatches each). Every cancel/interrupt table in the repo relies on them.

- Define the units (screen vs. document coordinates, wall clock vs. frames, bytes vs. characters, local vs. server time) once, here.

- When a document needs a new term, add it in the right section with a full paragraph before using it. Do not coin a synonym for an existing term.

- Prefer the product's own UI wording when it has one ("Archive", "Share link") and say so; prefer a plain word over the code's identifier otherwise (say "draft", not `pendingMessageBuffer`).

- Revise the glossary in the consistency pass: read every definition against the documents that use the term and fix whichever is wrong.

Two entries, for the shape of a definition:

> **Dirty.** A record is dirty from the first edit that differs from what was last saved until the next successful save. A dirty record shows a dot in its tab title, and leaving the page asks for confirmation. Reverting every edit by hand does not clear it; only a save or an explicit *discard* does.

> **Safe to interrupt.** A command is safe to interrupt while it is still reading: nothing has been written and Ctrl+C leaves the working directory as it was. It stops being safe at the first write, which the command announces with a line beginning "Writing"; from then on Ctrl+C finishes the file in progress before exiting, and a second Ctrl+C exits at once and leaves that file partial.

# goal.md template

`goal.md` is the standing prompt that drives drafting. It is given verbatim to whoever drafts and re-read at the start of every session. It is the one place the project's established facts, reading order, and working rules live. Product-specific parts are marked `{...}`; the "Things already established" section is empty at the start and fills in as foundations are written.

---

# Goal: complete the {product} product description

You are working in the `{repo-name}` repo. Read `README.md`, `glossary.md`, `foundations/{core-foundation}.md`, and `{area}/{pilot}.md` first. The README defines the purpose, the document template, the method, the structure, and the coverage table. The other three are the exemplars: match their depth, tone, and structure exactly. Your job is to write every document in the README's structure until the coverage table has no `not started` rows, then run a consistency pass.

## Source of truth

{The source repo} is checked out at `{absolute path}`. Describe the experience on {the surface: route, config, entry point} (`{path to that entry point}`), in {the default configuration, with nothing customized}. {Excluded thing} is out of scope.

For each document, read in this order before writing:

1. {Where the interaction state lives for the feature: the state machine directory and its child states; the domain object's util/controller.}

2. {The shared pipeline where relevant: the central dispatcher or router, the validation or hit-testing layer, and the managers or services that shape the experience.}

3. The tests in `{test directory}`. They are close to executable specifications of edge cases. Key files: {the list}.

4. UI behavior: `{ui directory}` ({hooks for actions, tools, shortcuts; components for the panels and menus}).

5. Defaults and thresholds: `{options file}` and `{constants file}`.

Do not describe code. Describe what the user sees and does. Technical detail goes only in `> Technical note:` block quotes, and only when the mechanism changes what the user would expect.

## Writing rules

- Follow the eight-section template in the README for every {tool, object, and action} document. Foundations, UI, and cross-cutting documents may drop sections that do not apply (a settings panel has no extended phase) but must still cover cancel/interrupt behavior wherever an interaction exists.

- Modifiers and cancel/interrupt go in tables, split by phase ({the product's names for "before extended" / "while extended"}) as in `{pilot}.md`. The interrupt rows and the order of cross-cutting concerns are fixed in the README; do not add, drop, or reorder them in a single document.

- Use the glossary's words. If you need a term the glossary lacks, add it to `glossary.md` in the right section with a one-paragraph definition, then use it.

- Sentence case for all headings. Direct, concrete language. No hedging, no marketing.

- State surprising behavior plainly and say why if the reason is in the code or a comment. If it looks like a bug, say so in "Open questions" rather than smoothing it over.

- Cross-reference other documents with relative links rather than repeating their content. {The input model} owns thresholds, click detection, modifiers, and the cancel/complete/interrupt definitions. Do not restate them; link.

- Every document ends with "## Open questions and verification" listing what was read from code but not confirmed by hand, followed by `Verified against {source repo} commit \`{sha}\`` using the current `git rev-parse --short HEAD` of {the source repo}.

- Mermaid `stateDiagram-v2` for each interaction's states. Keep it to the states the user passes through; omit internal bookkeeping states.

## Things already established (do not re-derive, do not contradict)

{Empty at first. As each foundation document is written, add its load-bearing facts here as one-line bullets: numbers, defaults, rules, naming decisions. The shape of it:}

- {Thresholds and timings: what separates the short path from the extended one, per input kind, measured in which units; debounce and timeout values; limits on size, count, and length.}

- {How variants are read: live, or latched at the start of an interaction; whether a role or flag can change mid-way.}

- {Naming decisions: e.g. the code's "Accel" is written as Ctrl/Cmd; the code's "workspace" is the UI's "project".}

- {What each gesture-ending event does and what dispatches it: cancel, complete, interrupt.}

- {Which features are unavailable in restricted states (readonly, a lesser role, offline, output piped).}

- {Defaults that many documents depend on: the default role and plan; the autosave interval and what "saved" means; configuration precedence and exit codes; scroll and zoom behavior; what is selected or focused on arrival.}

- {Which document owns which states of the hardest area, once decided.}

## Order of work

1. `foundations/` first, in this order: {list}. Everything else links to them.

2. `{hardest area}/` next, all {n} documents. This is the hardest part and the bulk of the experience. Read every {state file} before starting any of them, because the states hand off to each other and the documents must agree on where one ends and the next begins. {Say which document owns which states.}

3. The remaining `{area}/` documents, then `{area}/`, `{area}/`, `cross-cutting/`. These are independent of each other and can be drafted one after another once the foundations and {hardest area} documents exist to link to. If a fresh agent drafts one, give it this prompt, the four exemplars, and the specific document to write; then review every result yourself for consistency with the glossary and the established facts above before accepting it.

4. Consistency pass over the whole set: same term for the same thing everywhere, no two documents describing the same behavior differently, every relative link resolves, every document has a verification footer, every glossary term used is defined.

5. Update the coverage table in `README.md` as you go: `drafted` when written, never `verified` (verification by hand is a separate pass you are not doing).

## Working rules

- Commit after each document or coherent group of documents with a message of the form `docs: add {path}` or `docs: revise {path}`. {State the repo's convention on AI attribution in commits.}

- Do not modify anything in {the source repo}. It is read-only reference material.

- Do not add files outside the README's structure without updating the structure and coverage table to match.

- When a behavior cannot be determined from code and tests, write down what you could determine, put the rest in "Open questions", and move on. Do not guess and do not block.

- Depth bar: `{pilot}.md` is roughly {n} lines for a small {feature}. The {hardest area} documents will be longer; UI documents will often be shorter. Completeness matters more than length. Every state, every modifier, every cancel/interrupt row must be accounted for, even if the answer is "no effect".

- If you find that the README's structure is wrong for something you discover (a document that should be split, two that should merge), make the change, update the structure and coverage table, and note why in the commit message.

You are done when the coverage table has no `not started` rows, the consistency pass is complete, and everything is committed.

# Mapping the template onto a product

The document template is product-neutral: its sections are phases and families, not pointer events. What makes it concrete for one product is four decisions that every product has an answer to, and that must be made once, before the pilot, and then held constant across every document:

1. **The unit of interaction and its phases.** What is the smallest thing the user does that has a beginning, a possibly long middle, and an end? The "interaction, event by event" section narrates one of these. Its five subsections are phases, not pointer events: *starting*, *ending at once*, *becoming extended*, *while extended*, *finishing*.

2. **The variant axis.** What can the user hold, pass, or have set that changes the outcome of the same interaction? For a pointer product that is modifier keys; elsewhere it is flags, options, roles, settings, or the state of the thing being acted on. The "Modifiers" table is built on this axis.

3. **The interrupt list.** The fixed set of things that can happen *in the middle* of an interaction. This list is the same in every document, in the same order, and every cell is filled even when the answer is "no effect". It is the most valuable part of the method, because it asks the same questions of every feature, and gaps show up by comparison.

4. **The cross-cutting concerns, in order.** The things that touch every feature: permissions, history, containers, collaboration, offline. "Interactions with other systems" walks the same list in the same order in every document.

Write the answers into the README's "Document template" section (items 3, 4, 5, 6), define the interrupt words in the glossary's "events that end or interrupt" section, and do not change them after the pilot without revisiting every document.

Below are worked answers for four product kinds. A real product is usually mostly one of these with pieces of another; take the nearest column and adjust.

## Pointer-driven editor

Canvases, drawing and design tools, diagramming, maps, timelines, node editors, spreadsheets-as-grids. Also the right column for most native and mobile apps, with the OS lifecycle added to the interrupt list.

- **Surface:** one route or window, default configuration, nothing customized.

- **Unit of interaction:** a gesture. Phases: *pointer down* → *pointer up without dragging* → *becoming a drag* (crossing the distance threshold or a long press) → *during the drag* → *pointer up after dragging*. Rename the five subsections to these.

- **Variant axis:** Shift, Alt/Option, Ctrl/Cmd, Space, and anything the product adds (a tool-lock toggle, a pen-mode toggle). Two columns: held at the start, pressed during.

- **Interrupt list:** Escape; switching tools or modes; the events the product treats as "complete" (a menu opening, navigation, undo or redo); the events it treats as "interrupt" (a pinch beginning, another input device taking over); window loses focus; pointer leaves the window; the target is deleted, locked, or moved by something else; touch cancel; any product-specific mode that changes what happens after the gesture. For a mobile app add: app backgrounded, rotation, incoming call or notification, low memory.

- **Cross-cutting concerns:** containers, groups, locked or hidden objects, clipping, readonly, history, zoom, coarse pointer (touch), stylus, collaboration.

- **Foundations:** the input model (thresholds, click detection, modifiers, what cancels, completes, and interrupts), the object model, the tool or mode model, the camera or viewport.

- **Pilot:** a small tool with a real drag in it (a pan tool, a lasso, a ruler). **Hardest area:** the selection or main editing tool, which is many documents that must agree on where each state hands off.

- **Verification:** "device" means mouse, keyboard, touch, pen, a second user. The running product is the dev server or the installed app. A console handle on the app, if one exists, is for setting up scenes and reading state back, not for gesturing.

## Form-and-page web app

CRUD apps, dashboards, settings, checkout flows, admin panels, content management, anything where the user reads a page, edits fields, and submits.

- **Surface:** one role's view of the production app (or the staging app) with a fresh account and default settings. Say which role; a second role is usually a second repo or a cross-cutting document.

- **Unit of interaction:** a page or form lifecycle. Phases: *arrive* (route, what loads, what is focused, what is prefilled) → *leave without changing anything* (back, close, a link out; is anything recorded?) → *begin editing* (the first change: what becomes dirty, what validation runs, what buttons enable) → *while editing* (live validation, autosave, dependent fields, what the URL does) → *submit* (what is sent, what is optimistic, what is disabled meanwhile, the success and failure paths, where the user lands). Rename the five subsections to these.

- **Variant axis:** the user's role or plan, the record's state (draft, published, archived, locked by someone else), feature flags on by default, and the keyboard shortcuts the form honors (Enter, Cmd+Enter, Escape, Tab order). Two columns: "at arrival" and "during editing".

- **Interrupt list:** Escape; browser back or forward; reload; tab or window closed; navigation away by a link inside the app; network lost mid-request; request times out or fails with an error; session expires; the same record changed by another tab; the same record changed by another user; browser autofill or a password manager writes into the form; the window loses focus. Same list, every document.

- **Cross-cutting concerns:** permissions and roles, validation and error display, unsaved-changes handling, undo (if any), optimistic updates and their rollback, offline, notifications and toasts, search and filtering state in the URL, localization, accessibility, analytics side effects that the user can notice (emails sent, webhooks fired).

- **Foundations:** the data model in user terms (what a "record" is, what "saved" means, what is shared between users), the auth and role model, the navigation model (routes, what is in the URL, what is restored on return), the notion of dirty and saved, the notification model.

- **Pilot:** one small form with a submit and at least one validation rule (a rename dialog, a profile page, an invite form). **Hardest area:** the main editor or the main list-detail flow: the screens where most of the user's time goes and where records are created, edited, and moved between states.

- **Verification:** "device" means browser and viewport (desktop, mobile web), account role, network condition (offline toggle, throttled), and a second account in a second browser. The running product is staging or production with a throwaway account. Browser devtools stand in for the console: read the network tab to see what a submit sent, the application tab to see what was stored.

## Command-line tool

CLIs, build tools, package managers, database and deploy tools, anything invoked from a shell with arguments and producing output and an exit code.

- **Surface:** one binary at one version, default configuration, no rc file, a named shell (POSIX sh semantics unless the product is Windows-first), a terminal that is a TTY unless the document says otherwise.

- **Unit of interaction:** an invocation. Phases: *invoke* (argument parsing, what is validated before anything runs, what is printed first, what prompts appear) → *exits immediately* (help, version, a validation error: exit code, stderr vs stdout) → *begins running* (the first side effect, the first progress output, when Ctrl+C becomes unsafe) → *while running* (progress, streaming output, what is written when, what is idempotent) → *finishes* (final output, exit code, what was written to disk, what is printed on failure vs success). Rename the five subsections to these.

- **Variant axis:** flags and options, environment variables, config-file keys, whether stdout is a TTY or a pipe, whether stdin is a TTY, `--json` and other machine-readable modes, `--dry-run`, verbosity. Two columns: "changes what happens" and "changes what is printed".

- **Interrupt list:** Ctrl+C (SIGINT) once and twice; SIGTERM; the terminal closed (SIGHUP); stdin closed or stdout pipe closed (SIGPIPE); the network lost mid-run; the disk full or a file locked; a required file changed by something else during the run; running two instances at once; the process killed outright (what state is left on disk). Same list, every document.

- **Cross-cutting concerns:** configuration precedence (flag over env over file over default), output modes (TTY, piped, `--json`, `--quiet`), colors and unicode, exit codes, logging and verbosity, locking and concurrency, caching, network and proxies, permissions and sudo, shell completion, the update or version-check behavior.

- **Foundations:** the invocation model (how arguments are parsed, subcommand structure, how help is shown), the configuration model (precedence, where files live), the output model (streams, TTY detection, colors, exit codes), the state on disk (what the tool owns, lockfiles, caches), the notion of "done" and "safe to interrupt".

- **Pilot:** one leaf subcommand with a side effect and at least one flag (`init`, `add`, `rename`). **Hardest area:** the subcommand that does the most work with the most states (`build`, `deploy`, `sync`, `install`), which is usually several documents: one per phase of its run.

- **Verification:** "device" means operating system, shell, TTY vs pipe, and network condition. The running product is the binary at the commit. Most items are scriptable: the checklist's steps are commands, and the expected result is output and exit code, so a verification pass can be a script; say so in `verification/README.md` and still watch the TTY-only items (progress bars, prompts, colors) by hand.

## Chat, agent, and messaging products

LLM assistants, chat apps, support inboxes, anything where the unit is a message sent and a response received, and where the response may be long, streamed, and interruptible.

- **Surface:** one client (web, desktop, or mobile), one plan or role, default model or settings, a fresh account with no history.

- **Unit of interaction:** a turn. Phases: *compose* (what the input accepts, attachments, slash commands, mentions, draft persistence, what Enter and Shift+Enter do) → *sent and answered immediately* (empty input, a command that resolves locally, a validation error) → *sent and the response begins* (what is shown while waiting, when the message is committed to history, what can still be edited) → *while the response streams* (what updates live, tool calls and their display, what the user can do meanwhile: scroll, type the next message, switch conversations) → *the response completes* (final rendering, actions that appear, what is persisted, what happens to the draft). Rename the five subsections to these.

- **Variant axis:** the model or mode selected, attachments present, the conversation's state (new, continued, shared, archived), the user's role or plan, settings that change rendering (markdown, code blocks, reduced motion). Two columns: "set before sending" and "changed during the response".

- **Interrupt list:** Stop or Escape during streaming; sending another message while one is in flight; editing or deleting the message being answered; switching conversations; reload; tab or app closed; network lost; the response errors or is rate-limited mid-stream; session expires; the same conversation open in a second tab or device; a message arrives from another participant. Same list, every document.

- **Cross-cutting concerns:** history and persistence (what is saved when), sharing and permissions, search, notifications and unread state, attachments and their limits, rendering (markdown, code, images), keyboard shortcuts, offline and reconnection, multi-device sync, rate limits and quotas, accessibility.

- **Foundations:** the conversation model (what a conversation, message, turn, and draft are; what "sent" and "delivered" mean), the account and plan model, the navigation model (conversation list, routes, what is restored), the streaming and interruption model (what Stop does at each stage, what is kept).

- **Pilot:** the simplest complete turn (send a short message, receive a short response) or one local command. **Hardest area:** the composer and the streaming response together: every modifier, every interrupt, every attachment type, and what the user can do while a response is in flight.

- **Verification:** "device" means client (web, desktop, mobile), network condition, a second device on the same account, a second participant. Responses from a model are not deterministic; items about content say "a response" and check structure, timing, and state, not wording. The running product is staging with a throwaway account.

## Reading the columns together

- The **interrupt list** is always: the user's explicit abort; the user doing something else mid-way; the environment failing (focus, network, session, process); something else changing the target; the input device or channel changing. Derive the product's list from those five families and it will be complete.

- The **"ends quickly" phase** exists in every product (a click without drag, a form left untouched, `--help`, an empty message) and is where the most "nothing happens" claims live. Document it anyway; "nothing is recorded" is a claim the tester can check.

- **"Commit"** means whatever the product's durable step is: an undo entry, a saved record, a file on disk, a persisted message. The "ends after extending" phase says what is committed, in how many steps, and whether it can be undone.

- **Foundations** are whatever owns the numbers and the words: thresholds and timings, what "saved" or "selected" or "done" means, what each interrupt word means. Other documents link to them instead of restating.

# Verification templates

Two kinds of file: `verification/README.md` (the protocol) and one checklist per cluster of documents. Clusters follow the README structure (for example: foundations + the hardest area, the other tools + objects, actions + UI, cross-cutting).

## verification/README.md

```

# Hand verification

The feature documents were written from the code and the tests. This directory is the protocol for checking them against the running product, one observable claim at a time.

## What is here

| File | Covers |

| --- | --- |

| [{cluster}.md]({cluster}.md) | `{area}/*` and `{area}/*` |

| ... | ... |

Each file has one table per document. Each row is an item with a stable ID (`INVITE-07`, `INIT-12`), a priority, what it needs (a device, a role, a network condition, a second user), the claim with a link to the document section, the setup, numbered steps, the expected result, and a Result column for the tester. Items that cannot be checked by hand (design questions, things that need a product decision) are listed under each document as "Not checkable by hand".

Priorities: **P1** is an established fact, a claim many documents depend on, or a suspected bug; **P2** is an ordinary claim; **P3** is a number, a color, or a timing.

## How to run a pass

1. {Bring up the surface: the command, the URL, how to get a clean state for the pass and clean up afterward.}

2. Confirm the commit. Every document says `Verified against {repo} commit {sha}`. Run `git rev-parse --short HEAD` in {the source repo}; if it differs, the documents describe a different build and some failures will be drift, not defects.

3. Keep the documents open beside the {product}. Read the linked section before each item; the item is a summary, the section is the claim.

4. Work through P1 first across all files, then P2, then P3.

5. Record `pass`, `fail`, or `blocked` in the Result column, with a note for anything other than a clean pass. A fail is something the document says that the product does not do; a blocked item could not be run (no device, no second user, a prior failure in the way).

6. File every fail in [`bug-triage.md`](../bug-triage.md): if the entry exists, add a Status line quoting the item ID; if not, add an entry with the item ID under "Raised by". A fail is not automatically a product bug; sometimes the document is wrong, and the fix is to the document. Say which in the Status line.

7. When every P1 and P2 item for a document has passed or been filed, change its row in the [coverage table](../README.md#coverage) from `drafted` to `verified`.

## Devices and conditions

{One bullet per value the Device column uses (mouse, keyboard, touch, pen, a second user, specific files to drop, a readonly account, an admin role, offline, a piped stdout, a second device), with how to get it and any trap (a second tab is not a second browser; an offline toggle in devtools does not fail an in-flight websocket the way pulling the cable does; a trackpad reports inertial scrolling that a mouse does not; `--no-color` and a pipe are not the same condition).}

## Driving the product from a console or script

{If the surface exposes a handle (a global app object in the browser console, an inspector, a state dump command), say what it is good for: setting up the starting state exactly, reading state back after a real interaction, the handful of items whose expected result is a state rather than something visible. The real input should still be real input where the item is about input; use the console to observe, not to gesture. Say what the console cannot do (overlays drawn on animation frames stop when the window is occluded; synthetic key events may not reach the shortcut layer). For a CLI, most items are commands with expected output and exit codes and can be run as a script; say which items are TTY-only (prompts, progress, color) and must be watched.}

## Results so far

{Nothing yet, or: what pass was run, when, on what, against which commit, by what means, how many items, how many passed and failed, which triage entries the failures map to, and what the pass did not cover. Be exact about limits: "with the window occluded (so nothing visual was checked)". Say which documents, if any, are marked verified and why none are if none.}

```

## A checklist file

```

# Verification: {cluster name}

How to run this file: {one paragraph: the fresh-state setup specific to this cluster, which preferences must be at defaults, how to clear between sections, what each value in the Device column (`mouse` / `keyboard` / `touch` / `pen` / `sync`, or `admin` / `offline` / `piped`) means}.

## {area}/{document}.md

| ID | P | Device | Claim | Setup | Steps | Expected | Result |

| --- | --- | --- | --- | --- | --- | --- | --- |

| {PREFIX}-01 | P1 | mouse | {One sentence, the claim as the document states it} ([{section name}](../{area}/{document}.md#{anchor})). | {The scene and mode to start from.} | 1. {Step.}<br>2. {Step.}<br>3. {Step.} | {What is seen or read back, specific enough that pass/fail is unambiguous.} | — |

| {PREFIX}-02 | P2 | keyboard | ... | ... | ... | ... | — |

Not checkable by hand:

- {A design question or product decision the document raised; link to it.}

```

### Rules for items

- One observable claim per row. If a document sentence contains two claims, it is two rows.

- IDs are `{PREFIX}-NN`, prefix per document (`INVITE`, `INIT`, `COMPOSE`), numbered in document order, never renumbered once a pass has used them.

- The claim links to the section it summarizes. The section is the authority; the row is the summary.

- Setup states the starting state precisely (which record, which role, which fields filled; which files on disk, which flags, which environment; how many objects, which selected, which mode, which preferences).

- Steps are numbered, imperative, and include exact distances, keys, and timings where the claim depends on them ("Type a 65-character name", "press Ctrl+C within 1 s of the first progress line", "drag 200 px right", "wait 500 ms before releasing").

- Expected describes what is seen *and* what is not ("the dialog closes, no toast, the list is unchanged"; "exit code 2, nothing on stdout, one line on stderr"). For suspected bugs, say "Record what happens" and mark the row "(suspected bug)".

- Every suspected bug in the document gets a P1 row, even if the tester can only record the result.

- Every cancel/interrupt table cell that is not "no effect" gets a row. Every modifier cell that is not "no effect" gets a row.

- Numbers, colors, and timings are P3 unless many documents depend on them (the threshold that separates the short path from the extended one is P1).

- The Result column is `—` until a pass fills it. Results are recorded in place, with a short note after anything other than `pass`.

Expect on the order of a few dozen items per document; the count is driven by the document, not a target.