bewinxed/cawco/decision-page

Decision page

A decision page is an interview: one question per card, asked in the order the answers depend on each other, each answer drawn live with what it gets the person and what it costs them, and your recommendation with its reason. The page holds only what is still open. A press on an option is the pick, kept at once; a press on it again clears it. Every card stays open. A card is answered by a pick, a note, or a pin on it you replied to and resolved; once every card is answered, his picks and notes go to you by themselves a few seconds after his last change, and the Send at the page's foot only sends early. They come back through artifact_read.

The page is a page artifact whose source is a program in OpenUI Lang over CawCo's decision library: LIBRARY.md holds every component, its arguments, the syntax and the revision rules. You write the program, never markup. The show skill's step 1 comes first: the page opens with does: "pick" and an ask that heads the panel, so the page's title is the one line the hero needs. Each pick is kept by its decision's id with the program's hash. A revision keeps every pick whose id it still has. In a project the program is also committed to decisions/<name>/page.oui; a decision's after naming another page's decision (page#id) links the two pages, which the Decisions tab says on each ("After: …", "Unlocks: …"). A Send decides a project's page (his, or the hub's once every card is answered): the hub writes decisions/<name>/record.json and log.md from his picks (what he chose, who settled it and why, his note) and writes them again when he picks again, so read log.md for why a page was decided. Make tasks is a next step he may take on a decided page, never what decides it.

One way to ask

A choice reaches the person only as a decision card on a page, so every pick is in the Decisions tab, in the record, and something work can wait on. A single choice is a page with one card (or a few, for one topic): a project's Caw asks in a thread with a one-card page whose card his reply names by its link, drawn there as the card's chip. A question that is no choice between options (a fact only the person knows, a go-ahead) goes through ask instead.

The card

• Question: the choice in the person's plain words ("How dense is the task row?"), never a component, story or id.
• Options: 2–5 real answers. Each Option's line is what it gets them, its cost what it costs them, and its builds what picking it means building or changing, one sentence each. The card shows each as written, with no label before it, so each is a sentence that stands on its own: a line "The board moves while you are away.", a cost "Your Approve no longer continues the same call while you watch.", a builds "A new tray component and an onboarding step." (or "Nothing new: today's behaviour stays."). Never start one with "Gets:", "Costs:" or "Builds:". builds is the work, never the time it takes.
• One Recommended: exactly one option recommended, and the Decision's why is the one sentence that says why it. The card shows the why after that option's label ("Recommended: Per machine. …"), so the why never names the option again.
• Pick plus note: the card gives both; it asks nothing else. Leave the Decision's note out and its button reads "Add a note". When the pick needs a particular note, give note a noun phrase the button finishes ("a reason for the rollback" reads "Add a reason for the rollback").
• The same facts for every option: each line and each cost answers the same question in the same units, the Recommended option's cost included.
• One change per pair: a look card's options are the same real screen with one difference, said in each side's line; a behaviour card shows the states and the moves between them, playable.
• A reason that can be checked: the why names the fact that makes the Recommended option right (a number, a limit, what breaks), never only that it is better.
• A stable order: options stand in their own order (today first, small to large); never move the Recommended one to the top.
• Say what it changes: the question or the why says what the pick changes. Where something stands today, mark that option current.
• Restate what it rests on: a card that depends on an earlier pick names that pick in its question or why ("With Astro picked, …").
• Words first: the question, lines and costs carry the meaning; media shows it and never replaces it. Name an icon in words ("Attach"), never as a stand-in symbol or emoji. Figtree draws arrows (← → ↑ ↓), dashes, × ≠ ≤ ≥ and the like, but not ✓ ✗ ✕, the key symbols ⌘ ⌥ ⇧ ⌃ ⎋ ↵, ↔, ≈ or any emoji: write "Done" or "Command-K", for the hub refuses a program holding a character Figtree lacks.
• Few options: around five at most; split a bigger choice into two cards.
• Dials only for values on a picked option (its radius, its duration): add them to that card's media once it is decided.

Design options are drawn live. The component canvas (design-explore, component-canvas) is your working drawing, never a page for the person. For a design choice, give each option a component canvas of its own: a states file holding that option's story (RowQuiet.stories.ts, one PascalCase or kebab-case name before .stories, never dotted), opened with artifact_create({ kind: "component", name, title, does: "judge", ask, file }), and the Option's media a Preview of it naming the stories the card shows and the width they are drawn at: one story shown on a phone and a desk is two Previews of that one story ([Preview(id, null, ["Review"], 390), Preview(id, null, ["Review"], 1440)]), never a story per width. Every story is drawn at its real size, 1 CSS px per px, never scaled, so the person judges the real pixels: the page widens to the story, a card's options stand side by side only where every one fits at its width (two 390px phone designs sit side by side, two 1440px desk designs stand one under another), a design wider than the panel scrolls sideways in its well, and a page taller than the window scrolls inside its frame; each stands alone from its start, none of the canvas's working chrome. Options shown in several states compare state by state: give each state its own Preview, in the same order in every option ([Preview(id, null, ["Empty"], 390), Preview(id, null, ["Failed"], 390)]), and each option's nth piece stands on one row with the others' nth, the row as tall as its tallest; one Preview of many stories is one tall column that lines up with nothing. The widest piece sets every option's column, so a desk view among phone views stacks the options: show the desk views as their own pair in the Decision's media. A Preview of a whole screen (a page, a dev server's or a folder's preview: a timeline, a dashboard) is drawn at its real size too, never scaled: name its own layout width as width and it stands at that width and that screen's height, scrolling sideways in its well where the card is narrower; name none and it lays itself out to the card's full width. A phone's or a tablet's width (Preview(id, null, null, 390), anything under 1280) stands the screen upright at that device's whole shape, 390×844 and 768×1024, and a desk's (1280 or more) at 16:10, so a phone view is judged in its live frame, never a flat capture. Under it, Open full size brings it to the front of your panel. A choice that isn't visual needs no media.

Settled fixes from the person's pins are one compact card, a look Decision with id pins: the question "Fixed from your pins: does it look right now?", its why saying in plain words what each pin asked for, never quoting the person, the fixed state live in its media, and two options, "Looks right" (recommended) and "Not yet". Answer each pin in its own thread too (comment_reply).

Who decides

A choice that is not yours to make is a decision card with its kind; wait on the card — the hub settles it by the project's Who decides.

Every Decision names its kind, the 9th argument, and the hub refuses one without it: Decision("cache", "Where do builds cache?", [disk, s3], "Disk is free.", [], [], false, null, "approach").

The fleet's kinds of choice are listed in your instructions (Kinds:), each with the example that files a choice under it.

artifact_create and artifact_update answer where each card went: to the person (the card waits on him), to a member of Who decides that settles it (Caw, the advisor, common practice, an agent he added), or to you. A member that can't be reached sends the card to him, and the line says why. On a card that is yours, call settle({ card: "<page>#<card>", option, why, sources }): the pick is kept as yours, with your why, and the person can pick again. Wait on the card (waitsOn: "<page>#<card>" on a plan step or task) and build once it settles.

Steps