Cadora · design spec

Journey-first builds, by their surfaces

Everything needed to render or extend the journey-first method's screens — the exact tokens, the gate-review card's anatomy, the vision-addendum block, the journey document, the traceability check, and every state the gate can be in. The rendered components are live HTML; edit them here or lift the specs into Figma.

Palette

Semantic first · amber holds the gate, green passes it, red names the dead end

Amber--scr-amber · #ffd08aNeeds review · revision n/3 · addendum accent

Green--scr-green · #16c784Approve · traced · gate cleared

Red--scr-red · #fb7185Dead end · untraced · abort

Blue--scr-blue · #6ba5f0Document links · personas · endpoints

Ink--scr-bg · #0f172aCard ground

Canvas--scr-canvas · #111c2fInset · documents · rows

Panel--scr-panel2 · #162237The gate callout

Line--scr-line · #334158Borders

Text--scr-text · #f5f7fbPrimary · node id · step verb

Muted--scr-muted · #9aa8bcDoc body · kind labels · captions

Type & metrics

Documents read in sans, evidence in mono — the journey is prose, the gate is an instrument

Role	Family	Size / weight	Notes
Gate flag	sans	11px / 600	`NEEDS REVIEW` on the amber pill — the gate's one loud element
Document link	sans	13px / 400	Blue, clickable; the journey listed first with kind `JOURNEY`
Kind label	sans	10px / caps .05em	`JOURNEY · REQUIREMENTS · AUDIT`
Doc body	sans	12px / 1.65	Rendered markdown — prose stays sans; paths and values go mono-amber
Step number	mono	10px / amber	The fate walk's counter — bordered chip, one per step
Grep hit	mono	12px / 1.75	Matches amber; `(no matches …)` red — the dead end's one-line proof

Metric	Value	Metric	Value
Gate callout radius	11px	Gate accent	1px --scr-amber border
Document frame radius	8px	Addendum accent	3px amber left border
Doc / trace row padding	8px 10px	Revisions per gate	up to 3
Review nodes	requirements · design	Decision record	human-review.md

Anatomy — the gate-review card

The one surface where the journey meets its human

1234

NEEDS REVIEWrequirements — decide before design starts

aidlc-docs/inception/user-journey.mdJOURNEY · READ FIRSTopen

aidlc-docs/inception/requirements/requirements.mdREQUIREMENTSopen

Optional comment — prepended to the stage prompt if you request changes

ApproveRequest changesAbortdecision recorded in human-review.md

Ask ▾Does fate 2 say what the submitter sees while the claim waits?Send

1Gate flag — the node id and the stakes: requirements — decide before design starts. One amber pill per gate; nothing else shouts.

2Document list — the stage's artifacts, one click each. The journey is listed first with kind JOURNEY · READ FIRST: a reviewer who hasn't opened it can't have reviewed it.

3Comment — optional on approve, the whole point on request-changes: it is prepended to the stage prompt and becomes the first thing the re-run stage reads.

4Decisions — Approve (green) · Request changes (neutral) · Abort (red). Decision and comment are recorded in human-review.md. The conversational row beneath (Ask / Revise) is inherited unchanged from the human-review surface.

The vision-addendum block

Authority renders as a document, not UI — quoted, amber-accented

vision.md · addendumreviewed at the requirements gate

## User journey first (reviewed at the first gate)

Before designing, write aidlc-docs/inception/user-journey.md describing the end-to-end journey for the two personas — the submitter (documents in → decision + rationale back) and the claims reviewer (queue → inspect audit trail → resolve). … This document is a first-class deliverable of the requirements stage — it will be human-reviewed at the requirements gate, and the design must trace to it.

The 3px amber left accent marks text that creates a gate obligation. Two properties make the section enforceable: it names the exact file (absence is a fact, not a taste) and it states the review contract (a change request cites the vision, not the reviewer's mood). Always quote it verbatim — paraphrase weakens the citation.

The journey document

Persona chips · one fate walked per section · see / record at every step

user-journey.mdwritten by the requirements stage

persona · claim submitterpersona · claims reviewer

Fate 2 · MANUAL_REVIEW → human resolution

1Routed. The claim lands in the review queue; the submitter sees "in review"; the system records the routing reasons.

2Inspected. The reviewer opens the queue and reads the audit trail — what each agent found, and why it routed here.

3Resolved. approve or deny — with a mandatory reason.

4Recorded. Who / when / why in the audit trail; a second attempt is a clean error.

Persona chips are blue like links — people and documents are both things a reviewer follows. Every walk step is verb + what the person sees + what the system records; a step that only names what the system does is a feature list wearing a journey's clothes, and grounds for a change request.

The traceability check

One row per journey step · the tag names the design that serves it

✓queue → listthe reviewer opens the queue of waiting claimsGET /claims/review-queue

✓resolveapprove | deny, with a mandatory reasonPOST /claims/{id}/resolution

✗recordresolution entry — who / when / why — in the audit trailuntraced — request changes

The endpoints in the tags are the claims app's design outcome, not Cadora surface — the journey drew them out; Cadora only held the gate. A single ✗ row is a request-changes at the design gate, citing the vision's "the design must trace to it".

States

Every state the review gate can be in

Awaiting decision

gate requirements — needs review journey + requirements one click away design and construction idle until you decide

Approved

gate requirements — approved decision + comment recorded in human-review.md design starts

Changes requested · revision 1 of 3

gate requirements — changes requested · 1/3 comment prepended · the same stage reruns downstream still idle

Aborted

gate requirements — aborted decision recorded in human-review.md nothing downstream was built

Revisions are same-stage. Request-changes never advances the run: the comment is prepended, the stage reruns, and the gate reopens — up to 3 times. Downstream work cannot start on an unapproved journey, which is the entire mechanism: the dead end is caught before design inherits it.

What each decision does

Three verbs · approve releases, request-changes repairs, abort refuses

Decision	Effect	Recorded
Approve	The stage completes; downstream (design → construction) starts.	human-review.md
Request changes	Comment prepended to the stage prompt; the same stage reruns — up to 3 revisions — while downstream waits.	human-review.md
Abort	The run stops; nothing downstream is built.	human-review.md

Surface	How	Notes
Dashboard	cadora dashboard	Pending gate with clickable documents; Ask / Revise conversationally; decide in the browser.
Review files	cadora-review-decision.json	Drop it next to `cadora-review-request.json`; the run proceeds.
Headless / async	--review-file · --review-timeout 0	`0` waits indefinitely — for reviewers who step away.

Voice

A journey is walked, not summarized

Do	Not
Name the persona and the step — "the reviewer resolves, with a reason"	"Users can manage reviews"
Walk each fate to its end — every decision value gets a human owner	"MANUAL_REVIEW: see routing rules"
Pair every step — what the person sees, what the system records	A feature list in journey clothing
Cite the vision at the gate — "the design must trace to it"	"I'd prefer it differently"
Call a dead end a dead end	"Future work"

Structure and mechanics are taken verbatim from examples/aidlc-hitl.topology.yaml and the claims rebuild's vision.md; the gate card mirrors the run dashboard's review surface. Edit the rendered components in place, or hand the palette and metrics tables to a Figma library.