{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-choice-surface",
  "slug": "choice-surface",
  "title": "Turn generated choices into saved human decisions",
  "summary": "A chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state.",
  "category": "Team practice",
  "tags": [
    "web-choices",
    "human-review",
    "mobile"
  ],
  "sources": [
    {
      "label": "Codex workflows companion",
      "url": "https://lapis-fossil-vsbc.here.now/#choice-surface"
    },
    {
      "label": "Published workshop recording",
      "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
    }
  ],
  "sourceUnits": [
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Problem",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Move",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Smallest Useful Version",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The UI Contract",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Persistence Is The Trust Boundary",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Phone Workflow",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Tunnel Boundary",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Copyable Artifact: Mobile Decision Surface Brief",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/If It Goes Wrong",
    "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Claim Boundaries",
    "src/lib/content/sections.ts",
    "src/lib/content/sections.ts#choice-surface",
    "src/lib/content/sections.ts#recordingSpans"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 1151,
  "url": "/topics/codex-choice-surface/",
  "markdownUrl": "/markdown/codex-choice-surface.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-choice-surface.json",
  "headings": [
    {
      "id": "the-problem",
      "text": "The Problem",
      "level": 2
    },
    {
      "id": "the-move",
      "text": "The Move",
      "level": 2
    },
    {
      "id": "the-smallest-useful-version",
      "text": "The Smallest Useful Version",
      "level": 2
    },
    {
      "id": "the-ui-contract",
      "text": "The UI Contract",
      "level": 2
    },
    {
      "id": "persistence-is-the-trust-boundary",
      "text": "Persistence Is The Trust Boundary",
      "level": 2
    },
    {
      "id": "the-phone-workflow",
      "text": "The Phone Workflow",
      "level": 2
    },
    {
      "id": "tunnel-boundary",
      "text": "Tunnel Boundary",
      "level": 2
    },
    {
      "id": "copyable-artifact-mobile-decision-surface-brief",
      "text": "Copyable Artifact: Mobile Decision Surface Brief",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "claim-boundaries",
      "text": "Claim Boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Turn generated choices into saved human decisions\n\nA chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state.\n\nWhen an agent generates options, turn them into a **small picker**. Review it on a phone, tap the choices that should survive, dictate notes, submit, and make the agent continue from the saved JSON.\n\n```text\ngenerated options\n-> structured choice job\n-> Svelte + mdsvex picker\n-> token-gated mobile URL through a reviewed tunnel\n-> click/dictate feedback\n-> saved submission\n-> agent resumes from persisted JSON\n```\n\n## The Problem\n\nGenerated options are useful until they become a wall of text.\n\nThe agent offers five reasonable strategies for a checkout fix, billing webhook retry plan, auth/session tradeoff, QA screenshot triage, or design variation. You are away from the desk. The mobile chat thread now expects you to remember option names, type a careful answer, and trust the agent to turn that paragraph back into structured state.\n\nThat is where decisions get mushy.\n\n## The Move\n\nGenerated choices should **become data, not another paragraph**.\n\nThe agent should produce a **choice job** with stable option ids, titles, descriptions, risk notes, and proof hints. A small review UI renders those choices as cards. The human selects options, adds per-option feedback, adds overall feedback, and submits. The agent waits for the saved submission before continuing.\n\nUse this when the next step needs a human decision:\n\n- choose among generated UI variations\n- pick a billing webhook idempotency strategy\n- choose an auth/session migration path\n- approve or reject model-council recommendations\n- triage screenshot or debug-packet follow-ups\n- select the first implementation plan after a broad exploration\n\n## The Smallest Useful Version\n\nThe picker does not need to be elaborate. It needs stable ids, checkboxes, per-option notes, one overall feedback box, draft saving, and a submit button that writes durable JSON.\n\n```text\nChoice job:\n- jobId:\n- title:\n- description:\n\nOptions:\n- id:\n  title:\n  description:\n  risk:\n  suggested proof:\n  expected evidence:\n\nHuman response:\n- selected option ids:\n- per-option feedback:\n- overall feedback:\n\nResume rule:\n- continue only after a saved submission exists\n- resume from persisted JSON, not memory\n```\n\n## The UI Contract\n\n**Web Choices** uses a Svelte + mdsvex browser UI. The app shell can be branded and pleasant, but the generated choices stay plain JSON.\n\nKeep this boundary:\n\n- mdsvex owns the page/template shell\n- Svelte owns cards, selection state, feedback fields, save state, and submit controls\n- generated option text remains data\n- generated option text is not compiled as Svelte or mdsvex source\n\nThat boundary matters. A decision surface should not become a tiny CMS that compiles model output as app code.\n\n## Persistence Is The Trust Boundary\n\n**No saved submission, no continuation.**\n\nDrafts are for humans. Submissions are for agents.\n\n> I need you to make these decisions before I continue further, and so I look at it, I click the ones I want, give feedback on it, and then submit, and then it continues. So you create a really asynchronous feedback loop between your local agent and how you're talking to it on your phone.\n>\n> — John Lindquist\n\nThe durable state lives under a caller-selected human-in-the-loop output directory, commonly `.hitl-choice`:\n\n```text\n.hitl-choice/\n  current-job.json\n  drafts/\n  submissions.jsonl\n  submissions/<submissionId>.json\n```\n\nThe agent should wait until a final submission exists, then read selected option ids, per-option feedback, and overall feedback from the saved JSON. It should not infer the decision from visible UI state, draft text, or chat memory.\n\n## The Phone Workflow\n\n**The phone is for decisions, not implementation.**\n\n> Click, dictate, click, dictate has been the best workflow for me.\n>\n> — John Lindquist\n\nThe useful mobile loop is intentionally small:\n\n```text\ntap option\ndictate note\ntap option\ndictate note\nadd overall feedback\nsubmit\n```\n\nThis works best when the agent has already done the expansion work. The human does the selection work.\n\n## Tunnel Boundary\n\nA **reviewed, short-lived tunnel** can make the local picker reachable from a phone. Keep the specific tunnel product and hostname setup-specific unless the demo evidence is added and sanitized.\n\nThe important lesson is not the exact hostname. The important lesson is:\n\n- keep the local server alive while waiting\n- expose a short-lived token-gated URL\n- let the human submit structured feedback\n- resume from persisted JSON\n\nDo not treat a token-gated URL as full authentication. It is **useful friction, not a product security model**.\n\n## Copyable Artifact: Mobile Decision Surface Brief\n\n```text\nUse this when:\n- an agent generated several options\n- the human needs to choose or annotate them\n- the next step should not continue until the choice is saved\n- the human may be reviewing from a phone\n\nChoice job:\n- jobId:\n- title:\n- description:\n- options:\n  - id:\n    title:\n    description:\n    risk:\n    suggested proof:\n    expected evidence:\n\nUI requirements:\n- render options as cards\n- allow multiple selection when appropriate\n- collect per-option feedback\n- collect overall feedback\n- save drafts while editing\n- write final submission only on submit\n\nPersistence:\n- active job: .hitl-choice/current-job.json\n- drafts: .hitl-choice/drafts/\n- final log: .hitl-choice/submissions.jsonl\n- final packet: .hitl-choice/submissions/<submissionId>.json\n\nAgent stop rule:\n- wait for a saved submission\n- read selected ids and feedback from JSON\n- continue only from the persisted submission\n- report blocked if no submission exists\n\nSharing boundary:\n- do not expose real tunnel URLs\n- do not expose tokens\n- do not expose hostnames\n- do not expose or share private options or submissions\n- do not call the token full authentication\n```\n\nExample prompt:\n\n```text\nTurn these billing webhook strategies into a Web Choices job.\n\nEach option needs:\n- stable id\n- short title\n- concrete description\n- risk\n- suggested proof command\n- pass/fail evidence\n\nServe it as a phone-friendly picker, wait for the saved submission, then continue only from the persisted JSON.\n```\n\n## If It Goes Wrong\n\nIf the tunnel fails, keep the same job state when possible. Reuse the token only if it was not exposed; otherwise rotate the token, restart the tunnel, and verify the current job is reachable before asking for another decision.\n\nIf the server dies, inspect the output directory first. Restart with the same state if drafts or submissions already exist.\n\nIf the human says they submitted but the wait command has not returned, check `submissions.jsonl`, per-submission files, and whatever reviewed server logs or status endpoint the current implementation exposes before regenerating choices.\n\n## Claim Boundaries\n\nWeb Choices is a local human-in-the-loop pattern with a small web UI and durable files. It is not a production approvals system by default.\n\nVerify timeout behavior, tunnel behavior, mobile rendering, submission persistence, and data handling in the current setup before sharing executable setup instructions.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#choice-surface)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
}
