Prototype-Phase Skills & Design-Tree Flow

Investigation + visual map of the design/prototype pipeline. Audits the prototype-phase skills, diagrams the canonical flow, compares four real design trees from active repos, and proposes fixes for the gaps found — including the routing defect that triggered this run.

Status: review · Date: 2026-06-24 · Produced by: /investigate (no fixes implemented — proposals only)

⚠ Proposed divergence from current canon

Section 2 now depicts a proposed state-model-first pipeline that diverges from current canon. Today the design-tree convention treats state-model as an orthogonal, recommended-but-skippable per-branch attachment and keeps the route tuple a closed 6-skill sequence; create-ui-experiment is a per-branch experiment owner, "not a replacement top-level route position." This page proposes promoting both to first-class, mandatory inline route steps — state-model codifies the data architecture (app/flow/screen scopes, with a fast-pass fold for CRUD-trivial domains) before any UX/UI pass, and create-ui-experiment (mandatory, batchable) sits between ui-interview and the build plan. No canon (docs/skills/schema/tests) is edited by this page. The exact edits an executor would apply are spelled out in the companion proposal: docs/proposals/state-model-first-pipeline-refactor.md.

Table of Contents

The triggering defect — "stop after confirmation"
Flow diagram — the prototype-phase pipeline
Skill audit — 11 prototype-phase skills
What different design trees look like (4 real repos)
Gaps & issues in the real trees (with fixes — not applied)
Gate: the corrected post-approval route
Compile responses

1. The triggering defect — "stop after confirmation"

The invocation flagged a Post-Approval Route gate whose recommended option was "stop after confirmation", with the rationale that the design tree should not continue UI/prototype work until the repaired base flow is written and downstream branches are revalidated. The complaint: "stop after confirmation" is a useless option — after a canonical base-flow rewrite the route is state-model, not a terminal stop.

Root cause

Location: the alignment-page generator's gate vocabulary — docs/alignment-page-convention.md:69 lists post-approval route only as a gate-type label. It carries no canonical question text and no answer options, so each generated page authors its own options ad hoc.
What's wrong: with no canonical option set, a base-flow revision run rendered a degenerate "stop after confirmation" choice. That collapses the two distinct ideas the convention actually keeps separate — shed heavy build context (clear/fresh session) vs. terminate the pipeline — into one dead-end, dropping the real next step.
What the route actually is: per docs/design-tree-loop-convention.md §4 + §6, a base user-flow rewrite is a modify-back event. Re-opening the user-flow root marks the per-branch model_ref and all descendant UX/UI branches stale for re-validation. The correct next skill is state-model (revalidate the flow-anchored domain model) before any UX/UI/prototype work resumes. Note: under current canon state-model is off-route (an orthogonal, skippable per-branch attachment), which is partly why the post-approval gate had no real route to offer; §2 + the companion proposal recommend promoting it to a mandatory route step so the route the manifest already records is the route the convention draws.
Introduced by: pre-existing convention gap (no canonical post-approval-route option set), surfaced by the recent alignmeant base-flow rewrite (2026-06-23).

Claim validated against evidence

The user's correction is confirmed by the repo's own state. In /Users/georgele/projects/tools/dev/alignmeant/design/alignmeant/flow-tree-alignment-page-review.yaml, the same base-flow rewrite recorded:

Field in the live flow tree	Recorded value
`next_route.command`	`$state-model alignment-page-review`
`next_route.rationale`	"The base user-flow map was repaired; revalidate the flow-anchored domain model before continuing UX/UI branch work."
`decisions[].gate_answers` (post-approval route)	"continue state model revalidation"
`model_tree_status` / `revalidation.model_tree.status`	`needs-revalidation` → `$state-model`
5 downstream UX branches + 1 UI branch	all set to `needs-revalidation`

So the human reviewer already answered the gate "continue state model revalidation" and the manifest already encodes state-model as the next route. The generated "stop after confirmation" option contradicted the artifact it was attached to.

2. Flow diagram — the prototype-phase pipeline (proposed state-model-first order)

The proposed single solid pipeline: user-flow-map translates the journey map into design language, then state-model (blue, now a first-class main-line step) codifies the data architecture across three scopes — app · per-flow · per-screen, with a fast-pass fold for CRUD-trivial domains — before any UX/UI pass. ux-variations and ui-interview follow, then create-ui-experiment (now a main-line step, mandatory · batchable) validates each approved UI branch clickably before user-flow-map --prototype-build-plan synthesises the build plan. Inline sub-skills are purple (design-inspirations off ui-interview, uat off prototype); the modify-back revalidation arc (red) — the loop the triggering defect concerns — now returns to both state-model and user-flow-map. Boxes are sketch-styled; text is clean per the project Excalidraw convention.

route pipeline skill orchestrator / state-model step inline sub-skill modify-back / revalidation

Text fallback for the **proposed** state-model-first flow diagram
Step	Skill (node)	Produces	Then →
1	user-flow-map orchestrator	flow-tree root + one user-flow branch per flow (journey map → design language)	state-model
2	state-model first-class	data architecture codified across app / per-flow / per-screen scopes (`model_ref`); fast-pass fold for CRUD-trivial domains	ux-variations
3	ux-variations pipeline	≤5 UX variation branches on a modelled flow	ui-interview
4	ui-interview pipeline	UI experiment branches (calls design-inspirations inline)	create-ui-experiment
5	create-ui-experiment mandatory · batchable	clickable validation for every approved UI branch; deferrable so all interviews can finish first, then experiments in one pass	user-flow-map --prototype-build-plan
6	user-flow-map --prototype-build-plan orchestrator	ordered prototype build plan	prototype
7	prototype pipeline	runnable variants + decisions[] (origin of modify-back)	uat
7a	uat --variant-evaluation sub-skill	human evaluation evidence	consolidate-prototypes
8	consolidate-prototypes pipeline	consolidated MVP + AFPS graduation	research-roadmap --post-prototype
8a	research-roadmap --post-prototype	narrow pre-spec cleanup pass	spec-interview
9	spec-interview terminal	`specs/{topic}.md` production spec	roadmap (implementation)
↺	modify-back loop	`modify` decision with `targets[]` re-opens a `user-flow` / `state-model` node	descendants → needs-revalidation → state-model

3. Skill audit — 11 prototype-phase skills

Every active skill in the design/prototype pipeline, its location, role, and stage-4 canonical deliverable. All run the same 5-stage session flow (interrogation → research → design → plan → implement-scoped) per docs/design-tree-loop-convention.md §2.

Skill	Ver	Role	Tree node grown	Stage-4 deliverable	Routes out →
`user-flow-map` orchestrator packs/product-design	v1.6	Root orchestrator; one user-flow branch per flow; owns build-plan synthesis	root + user-flow branches + build plan	`flow-tree-{t}.yaml`, `user-flow-{t}.md`, `prototype-build-plan-{t}.md`	`/state-model` → `/ux-variations`
`state-model` first-class step packs/product-design	v0.8	Proposed: first-class step; codifies data architecture (app/flow/screen) before UX/UI. (Canon today: orthogonal skippable per-branch attachment.)	model attachment (`model_ref`); proposed app/screen scopes	`model-tree-{t}.yaml`, `domain-model-{t}.md`	`/ux-variations`
`ux-variations` pipeline packs/product-design	v0.28	Grows ≤5 UX variation branches on a modelled flow	`ux_variations[]` branches	`ux-variations-{t}.md`	`/ui-interview`
`ui-interview` pipeline packs/product-design	v0.27	Evaluates one UX branch; grows UI experiment branches; HTML mockup	`ui_experiments[]` branches	`ui-{t}.md`, `ui-requirements-{t}.md`	`/user-flow-map --prototype-build-plan`
`create-ui-experiment` inline step packs/product-design	v0.1	Proposed: inline clickable validation between `ui-interview` and the build plan (mandatory · batchable). (Canon today: experiment owner, not a default buildout path.)	UI-experiment evidence note	`experiments/{t}/{id}/`	`/user-flow-map --prototype-build-plan`
`prototype` validation packs/product-design	v0.19	Builds runnable prototypes; records decisions; origin of modify-back	prototype + `decisions[]`	`prototypes/{t}/variation-N/`	`/uat --variant-evaluation`
`uat` sub-skill packs/product-testing	v0.14	Human variant-evaluation / acceptance plans + evidence	evaluation evidence	`research/uat-variant-evaluation-{t}.md`	→ parent (`/consolidate-prototypes`)
`consolidate-prototypes` pipeline packs/product-design	v0.17	Converges evaluated branches into one MVP; AFPS graduation	consolidated MVP node	`prototypes/{t}/consolidated/`, `afps-graduation-{t}.md`	`/research-roadmap --post-prototype`
`spec-interview` terminal packs/product-design	v0.17	Production deep-dive; owns Production Ready Approval	spec node	`specs/{t}.md`	`/roadmap` (implementation)
`design-inspirations` sub-skill packs/product-design	v0.3	Inline web-research feeder for ui-interview	(no node — feeds parent)	`design-inspirations-{t}.md`	→ parent (`/ui-interview`)
`consolidate-variations` deprecated packs/product-design	v0.0	Compatibility alias → `consolidate-prototypes`	none	none (delegates)	`/consolidate-prototypes`

Current canon (per docs/skill-next-step-contracts.md §8): closed 6-skill route user-flow-map → ux-variations → ui-interview → prototype → consolidate-prototypes → spec-interview, with state-model a recommended-but-skippable per-branch attachment, create-ui-experiment an off-route experiment owner, and research-roadmap --post-prototype the graduation-aware cleanup pass before spec.

Proposed (this page; see docs/proposals/state-model-first-pipeline-refactor.md): promote both into the inline route — user-flow-map → state-model → ux-variations → ui-interview → create-ui-experiment → user-flow-map --prototype-build-plan → prototype ⇄ uat → consolidate-prototypes → research-roadmap --post-prototype → spec-interview. state-model becomes mandatory (app/flow/screen scopes, fast-pass fold); create-ui-experiment becomes mandatory-but-batchable.

4. What different design trees look like (4 real repos)

Four flow-tree manifests found across active repos show the schema at different maturities. They are the basis for the gap analysis in §5.

A — Canonical reference · `agentic-skills/design/flow-tree-sample.yaml` (schema v0.3)

The fully-formed shape: nested branches, per-branch model_ref, the deterministic branch_order_override, decisions[] with a modify that re-opens upstream nodes, and a populated prototype_build_plan.

root: invoice-approval (v0.3, flat) └── submit-and-approve [ready-for-ui] model_ref ✓ journey_sequence=1 ├── guided-wizard [approved] eval_priority=1 │ └── wizard-stepper (UI) [approved] → decision: approve → built (variation-1) └── single-page-dense [retry-needed] eval_priority=2 └── dense-table (UI) [rejected] → decision: MODIFY → targets:[model_ref, submit-and-approve]

B — Mid-revision · `alignmeant/design/alignmeant/flow-tree-alignment-page-review.yaml` (schema v0.1, product-path)

The exact scenario behind this investigation: the base user-flow map was rewritten; next_route → $state-model, the model and all 5 UX + 1 UI descendants set needs-revalidation. Note it uses the legacy top-level model_tree_ref, not per-branch model_ref.

root: alignment-page-review (v0.1, product-path: research/alignmeant) ├── 9 user-flow branches [all approved] (Orient→Review→Respond→Preview→Handoff→Verify) │ model_tree_ref → model-tree-…yaml [needs-revalidation] └── ux_variations (5) [ALL needs-revalidation] ├── trust-first-review-page │ └── ui-exp trust-first [needs-revalidation] (was approved under prior flow) ├── change-first-revision-workspace · guided-approval-wizard └── operator-console · agent-handoff-lineage-flow next_route: $state-model alignment-page-review ← the correct post-approval route

C — Broad fan-out · `gblock-party-redux/design/flow-tree-personal-workstation.yaml` (schema v0.1, flat)

Seven user-flow branches, only one with UX variations grown. Uses the older branch schema (flow_paths, screens, ux_variations_status, decision) and routes through the deprecated consolidate-variations. No state-model attachment at all.

root: personal-workstation (v0.1, flat) route includes consolidate-variations ⚠ (deprecated) ├── onboarding [not-started] ├── monitoring-start [in-progress] ← 5 UX variations (proposed) │ ├── v1-operator-console v2-card-mosaic(baseline) v3-kanban-pipeline │ └── v4-command-first v5-glanceable-stream recommended_next: v2-card-mosaic ├── approval · recovery · device-handoff · diff-review · settings [all not-started] (no model_ref / model_tree_ref on any branch) + 6 open_questions, proposed_flowmap_amendment pending

D — Pre-v0.1 schema · `omega-war/design/unthinkable/flow-tree-tactical-battle.yaml` (no schema_version, product-path)

An older structural shape: root → parent_user_flow → ux_variations (single flow, no branches[] array), branch_routing instead of the deterministic priority stack, and a build plan that references UX variations (tactical-entry-demo, after-action-demo) that do not exist in the ux_variations list.

root: unthinkable → parent_user_flow: tactical-battle (no schema_version) └── ux_variations (5) ├── guided-battle-drill [planned] recommended_for_ui_interview ✓ ├── deployment-plan-first [ui_approved] → UI review approved → built └── commanders-… · map-first-… · resilient-skirmish-loop [planned, deferred] prototype_build_plan: 3 built, 4 deferred ⚠ items reference ux_variations 'tactical-entry-demo' & 'after-action-demo' — absent from ux_variations[]

5. Gaps & issues in the real trees (fixes proposed, not applied)

Findings mapped to evidence and a suggested fix. No fixes were implemented — this section is the proposal record only.

#	Tree	Gap / issue	Evidence	Suggested fix (not applied)	Sev
G1	Convention	"stop after confirmation" rendered as a post-approval route option with no canonical next-step	`alignment-page-convention.md:69` lists the gate type but no option set	Add a canonical post-approval-route option set to the convention: (a) continue next route now, (b) clear context then run next route, (c) revalidation pause → state-model. Forbid a bare "stop" with no route.	High
G2	B alignmeant	Uses legacy top-level `model_tree_ref`, not per-branch `model_ref` — convention marks the top-level pointer back-compat only	convention §1 "primary linkage is `branches[].model_ref`"; tree has `model_tree_ref` only	On the pending `state-model` revalidation, attach `model_ref` per user-flow branch; retain top-level pointer only as back-compat.	Med
G3	B alignmeant	9 user-flow branches still `approved` while the base flow was rewritten — descendants are stale but parents not re-marked	revision summary changes the base process; branches keep `status: approved`	Confirm whether the 9 branches survived the rewrite verbatim; if the base process changed, mark affected user-flow branches for re-confirmation, not just UX/UI descendants.	Med
G4	C gblock	Route array contains deprecated `consolidate-variations` instead of `consolidate-prototypes`	`route:` list line; alias is `deprecated: true`	Update the `route` tuple to `consolidate-prototypes` so the manifest matches the live skill.	Med
G5	C gblock	No domain model anywhere; `ux-variations` already in-progress though convention requires `model_ref` confirmed first	convention §6 "ux-variations requires the branch's model_ref confirmed"; no model node exists	Run `state-model personal-workstation` for at least the `monitoring-start` branch before its UX variations are approved; backfill `model_ref`.	Med
G6	C gblock	`proposed_flowmap_amendment` (merge S5/S6) parked unresolved — UX variations built on a flow map the run itself flags as needing edit	tree note: "Pending flow-map owner acceptance — do not silently edit approved flow-map"	Resolve the amendment through `user-flow-map` (accept/reject the S5/S6 merge) before approving the 5 UX specs that depend on it.	Med
G7	D omega-war	Build-plan items cite UX variations absent from `ux_variations[]` (`tactical-entry-demo`, `after-action-demo`)	`prototype_build_plan.items[].source_ux_variation` has no matching `ux_variations[].id`	Either add the two demo variations as real `ux_variations` nodes, or relabel the build items as derived demo artifacts of `deployment-plan-first` so every build item traces to a real branch.	High
G8	D omega-war	Pre-`branches[]` shape (`root→parent_user_flow→ux_variations`) + `branch_routing` instead of deterministic priority stack; no `schema_version`	convention §1 node types + §3 deterministic branch selection; manifest predates both	Migrate to the `branches[]` + `schema_version: v0.3` shape with `journey_sequence`/`evaluation_priority` so deterministic selection applies.	Med
G9	All real trees	Schema drift: three different schema versions in flight (v0.1 ×2, none, vs v0.3 sample)	headers across the four manifests	Provide a one-shot manifest migrator (sample v0.3 is the target) and run it per repo; out of scope for this investigation.	Low

6. Gate: the corrected post-approval route

Post-Approval Route (corrected) — required

After a canonical base-flow rewrite and confirmed page update, what should happen? (Replaces the degenerate "stop after confirmation" option.)

Revalidation pause → state-model — run /state-model {topic} to revalidate the flow-anchored domain model; descendant UX/UI branches stay needs-revalidation until the model is re-confirmed. (Recommended — matches the live next_route in the manifest.) Continue now in this session with /state-model {topic} (only if little build context is held). Clear context, then run /state-model {topic} in a fresh session (default when heavy build context is held). Hard stop — no further design work intended (terminal; not a routing answer). Only valid when the user is abandoning the pipeline, never as the recommended post-rewrite default.

The defect was treating the third/fourth ideas as one "stop." Clearing context is a session choice; the route is still state-model. A true terminal stop is a separate, rarely-correct answer.

Under the §2 proposal, state-model is a mandatory route step rather than a skippable sibling — which makes "the route is state-model" structurally guaranteed here, not a recommendation the gate had to reconstruct. The gate options themselves are unchanged.

Scope / fixes gate — required

This page proposes fixes (§5) but applied none. Which should become tracked work?

G1 — add canonical post-approval-route option set to alignment-page-convention.md G7 — fix omega-war build-plan items that reference non-existent UX variations G2–G6, G8 — per-repo manifest revalidation/migration (each in its own repo) None yet — alignment page is the deliverable; defer fixes

7. Compile responses

When you've answered the gates above, compile to YAML for the agent to consume.

Awaiting answers…

Evidence sources: docs/design-tree-loop-convention.md, docs/skill-next-step-contracts.md, docs/alignment-page-convention.md; flow-tree manifests in agentic-skills, alignmeant, gblock-party-redux, omega-war; SKILL.md audit of 11 prototype-phase skills.