# AI patterns — AI proposes, the human decides Which surface an AI outcome takes, and the laws that hold inside each. Which entry draws it is [catalog.md](./catalog.md); its props are `dist/.d.ts`. ## The one law **Nothing a model produced is written without a person deciding it** — and the split turns on WHO supplied the values, never on how confident the model is. | What is happening | What the person sees | |---|---| | Modifying an existing record | a review: the current value, the proposed one, and a per-field decision | | Creating new records from a DOCUMENT | a review: the extraction beside the source it came from | | Creating new records a human TYPED | no review — they already decided; validate and write | ## Which AI surface — decide by the OUTCOME's shape, not the task's topic A command with a result is a composer; a run with steps is a live feed; a set of proposed changes is a review; a question the model needs answered is a clarification; a whole run that owns the screen is a run pane. ## The trigger — a paid action is pressed exactly once **Same-tick feedback**: the control disables on press, not on the response. **Single-flight in app code too** — a second press while a run is in flight is dropped by the caller, because the SDK backstops runs and not workflows. ## Stopping — the exit is part of the trigger The verb is **`cancel`, never `abort`**. **Closing a dialog must CANCEL**, or the run keeps spending after the reader has left. **Stop lands where the run STARTED**, and **the control is PINNED, in the footer** — a stop that scrolls away is not a stop. ## Show the work — the live run feed **ONE row for the whole run, over a TRACE alone.** A sentence the agent wrote to the reader never folds: no part says whether it is a plan or the finding, so a fold over prose guesses wrong where it costs. The answer waits for settle. **Progressive disclosure** — steps group into activities, and expanding works the same live and settled. A call an operator decided on — approved or refused — stays out of every fold. **No step count**: a number that cannot be known reads as a promise. **An unsettled row BREATHES**, and a run with no parts yet renders that breathing row rather than an empty box. Reasoning shows only when the model produces it. **Errors are two kinds, both surfaced, neither shouting** — a step that failed and a run that failed are different rows. Follow-the-tail scrolling belongs only to a feed that took the job of showing every step. **Answering an awaiting call** is its own control — the read-only amber "awaiting" row has an interactive counterpart, and the reader answers there rather than in prose. ## Review before apply — two atoms and a hook, composed into your screen **There is no review CONTAINER, deliberately.** The shapes below differ in layout and share their laws, so the kit ships the atoms — a before/after value, a decision mark, and a change-set hook — and the screen composes them. | The shape | What the row is | |---|---| | A record's fields | one field, its current value, its proposed value | | A record SET | one record, with its own accept/reject | | A conflict | two sources that disagree, and the magnitude between them | | An ATTACHMENT | the file, and what it was matched to | | A DOCUMENT SET | one document per row, with the extraction behind it | | A record being CREATED from a document | the whole record, beside its source | | Display-only | no decision — the value and where it came from | A set that mixes KINDS defaults per kind: the hook's `initial` also takes a per-id map. ### The laws that survive the container **Nothing auto-applies.** **Editing IS the review** — a value the reader corrects is accepted by that act. **Gate the commit on what will actually be written**, never on the count of rows shown. **A decided row's Keep/Drop must be reachable from BOTH directions** when the default is accepted, or a reader cannot undo their own first decision. **The mark rides the LABEL, and the value sits in its own slot**, so a long value truncates where the block wraps rather than pushing the mark off. **The reason goes above the verdict.** **Show the WHOLE thing, not just the parts that moved** — a diff of three fields inside a record of twenty is not a decision anybody can make. **The fixture must not flatter**: a review demo whose every row is an improvement teaches nothing about the row that is wrong. **Provenance belongs at the bottom of the section**, not beside every value. **UNKNOWN is not zero**, **a change that is not to the VALUE must diff the thing that DID change**, and **a conflict candidate is never pre-selected**. ## Ask back A question with selectable answers, each carrying a one-line description, freely switchable before the run continues. A wizard is the same thing across several questions. ## The whole run in a dialog A scope, a pane and an actions bar. Pass an on-landing handler if the run's RESULT drives anything. **The parked question REPLACES the feed — that is the contract, not a style.** **Mount the actions wherever the run drives the surface, never gated on one phase.** The run is a SHAPE, not an import: anything matching it drives the pane. Customize through the seams, or drop to the primitives. ## After the run — a record that FILLS UP from more than one writer **An unwritten value must not render like a written one.** **A machine's prose and a person's must not share a treatment.** **Model prose arrives with its own type ladder — take it away at the door**: render it through the kit's markdown surface so a model's `##` becomes the screen's rung. ## Confidence, provenance and findings Confidence is shown WITH its basis or not at all — the meter and the level phrase head the block, and what was checked follows. Provenance is a sources list, at the bottom of what it supports. **A finding is evidence, not a write.** It is described here because AI produces most of them, NOT because it is an AI component: a rules-derived contradiction is as much a finding as an extraction's. Severity is functional colour, like every other valence. ## Session, not chat An AI surface in a record is a session about that record: it starts where the reader is and ends when the work does. It is not a transcript to scroll back through. ## Five proven shapes A canvas (the model proposes artwork and a human directs it), an answer desk (a question, an answer and its sources), a document desk (a document beside its extraction), an intake desk (a queue of arrivals to file), and a triage or ranked pick (a population ordered by what needs the reader first).