design(constitution): the ratification ritual — recommendation for the drafting flow (choices propose, prose disposes)

[Hmbown]

Design input for the constitution-first setup lane (PR #3861's wizard; this checkout has no wizard yet — verified, the onboarding today is welcome → language → API key → trust → tips and never mentions the constitution). The question posed: should constitution drafting be open-ended or multiple choice, and what would the best-designed version of this ritual look like?

Walking through it as the user

Someone just installed a terminal coding agent. They are impatient — every screen between them and the first prompt is a cost they're paying on faith. Now we ask them to write the law their agent will live under. Two failure modes, one per format:

• Open-ended-first fails the novice. The constitution matters most to the user with the least experience to write one — they haven't worked with the agent yet, so "what should your agent never do?" hits blank-page paralysis. They type something generic ("don't delete stuff"), feel unsure whether it even does anything, and never look at the document again. The cold-start paradox: you can't author good law about an agent you haven't lived with.
• Multiple-choice-only fails the ritual. A wall of radio buttons reads as a EULA/settings form. Users mash defaults, and "ratification" becomes theater — nothing in the document is theirs, so the trust the ceremony is supposed to build never forms.

The HCI principle underneath: recognition beats recall. Users can recognize the posture they want far more reliably than they can generate it. But ownership requires authorship — even one self-written clause converts the document from "their terms" into "my constitution."

Recommendation: choices propose, prose disposes

1. Ship a default constitution good enough to adopt in one keypress. "Adopt the standard constitution" must be a first-class path (Apple pattern: defaults so good that skipping is safe), not a guilt-tripped skip. Target ≤90 seconds on this path, resumable, never re-shown.
2. 3–4 multiple-choice posture questions, maximum. One per screen. Work style (review-first ↔ momentum), risk posture (what always requires asking), communication (terse ↔ explanatory), and optionally scope (paths/secrets that are off-limits). Two rules make these feel like law rather than settings: (a) each option shows a one-line consequence preview at the moment of choice ("Plan mode will be the default; the agent proposes before it edits"); (b) each answer visibly rewrites an amendment in the draft document on screen — the user watches their choice become a clause, not a hidden toggle.
3. One optional open-ended prompt at the end: "Anything you'd add, in your own words?" This is where model-assisted drafting earns its place — the user speaks plainly, the model drafts a law-like clause, and the clause appears in place with a diff highlight for approval. Freeform input is an amendment channel, not the primary interface. (The untrusted-JSON → sanitize → bound → preview → explicit-ratify gate described in feat: v0.8.67 constitution-first setup — model-assisted onboarding, runtime posture, cleanup #3861 is exactly right; nothing becomes law unratified.)
4. Make ratification feel like ratification. The full document, the user's amendments highlighted, and a deliberately weighty confirm — typed ratify or a distinct key, not Enter-mash. This is the product's signature moment; it deserves the Touch-ID-setup treatment, not an OK button.
5. Law must live after the ceremony or the ceremony was theater. /constitution to read the document in force and its provenance (see ux(constitution): no in-app way to read the constitution, and a custom override without the env flag fails silently #3928 — today there is no in-app way to read it at all), and /constitution amend for later changes — the constitution evolves by amendment, not by re-onboarding. The cold-start paradox resolves here: a week in, the user does know what they want; the cheap amendment path is where the real constitution gets written.

Why hybrid, in one sentence

Multiple choice for the load-bearing decisions because recognition scales to novices; open-ended as an optional amendment channel because a single self-authored clause is what makes the document theirs; and a one-keypress default path because the users who choose it are telling you something true about their trust budget — respect it, and let the living /constitution surface earn the rest.

Supporting evidence from this checkout

The concrete pre-wizard gaps are filed separately: no in-app constitution viewer + silent override failure (#3928), trust-or-quit onboarding step (#3926), hard API-key gate (#3927), onboarding copy drift (#3929), and no scaffold/validation for .codewhale/constitution.json — the repo-local law that /init already tells users to adopt but which currently requires hand-authoring JSON against a schema only readable in Rust source (project_context.rs:51-66; a /init constitution scaffold with schema feedback through the existing project-context warnings would be the natural precursor to the wizard).