Cadora · journey-first builds
An agent-built app can be engineering-complete and still lose the human: every requirement covered, and the person who resolves the hard case never designed. Journey-first building closes that gap with pieces Cadora already has — the vision demands a journey document, a human reviews it at the requirements gate, and the design must trace to it.
Cadora rebuilt an insurance claims adjudication engine — four specialist agents, a supervisor emitting APPROVED / MANUAL_REVIEW / DENIED, a FastAPI surface, an offline mock mode. The generated requirements were excellent on engineering: full FR/BR/API/NFR/AC coverage, a traceability matrix. But grep for the human and the story stops: MANUAL_REVIEW exists as a decision value, two routing rules, and a test case — no queue, no reviewer view, no resolve step. The human step of the claims process was named but never designed.
Every matched line is good engineering. None of them designs the person. That's the gap the method's default artifacts don't catch — a user journey isn't among them, so nobody had to walk the claim to its end.
The operator caught it at the review gate by asking two questions — where is the user journey? what does the human decide? — and fixed it at the source. Not a patch to the generated docs, not a new Cadora feature: an addendum to vision.md that makes the journey a named deliverable and turns the dead end into scope.
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). Cover the three claim fates (clean APPROVED, MANUAL_REVIEW → human resolution, DENIED on exclusion) step by step, naming at each step what the person sees and what the system records. 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.
MANUAL_REVIEW is a queue, not a dead end. A claims reviewer must be able to: list the claims awaiting review (with each claim's audit trail and the reasons it was routed), and resolve one with an explicit decision (approve | deny + a mandatory reason). Resolution produces the final decision, appends a resolution entry to the audit trail (who/when/why), and is idempotent-safe (a claim can be resolved once; a second attempt is a clean error).
The run itself doesn't change: cadora run examples/aidlc-hitl.topology.yaml --vision vision.md --hitl. With --hitl, Cadora pauses at every node marked review: true — in this topology, requirements and design — before any downstream work starts.
On the next run, user-journey.md arrives with the requirements — two personas, three fates, each walked to its end. The fate that used to be a dead end now reads as a loop: queue → inspect → resolve → recorded, with the person and the system named at every step.
persona · claim submitterpersona · claims reviewer
Three fates, end to end: clean APPROVED · MANUAL_REVIEW → human resolution · DENIED on exclusion. Each step names what the person sees and what the system records.
MANUAL_REVIEW; it lands in the review queue. The submitter sees "in review"; the system records the routing reasons in the audit trail.approve or deny — with a mandatory reason. No silent buttons.The run pauses at the requirements gate with the stage's documents one click away — the journey listed first. The reviewer walks each persona through each fate, asks questions in place, and then decides: approve, request changes, or abort — all before design starts, all recorded in human-review.md.
Away from the dashboard? The gate writes cadora-review-request.json; drop a cadora-review-decision.json beside it and the run proceeds. For asynchronous reviews, run with --review-file and --review-timeout 0 (wait indefinitely).
When the journey is thin — say, the reviewer persona still has no resolve step — the gate doesn't wave it through and it doesn't kill the run. Request changes prepends the comment to the stage prompt and reruns the same stage, up to 3 revisions, while everything downstream waits. The gap is fixed where it was made, before design inherits it.
At the design gate, the same reviewer runs a short check: each journey step against the piece of design that serves it. For the fate that used to dead-end, every step now lands somewhere concrete — and those endpoints are the claims app's design outcome, drawn out by the journey; Cadora's part was holding the gate until a human asked.
An untraced step is a request-changes at the design gate, with the vision's own line as the citation: "the design must trace to it."
The frames above reproduce real surfaces — the generated requirements under grep, the vision addendum and journey document as written, and the run dashboard's review gate — rendered as editable HTML rather than raster captures. The gate mechanics themselves are documented in the human-review doc and the method pack in the AI-DLC doc; journey-first is those two composed, so the built app's human story ships the way its code does: reviewed, versioned, and traced.