Workflow — UX discovery¶

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.


Workflow id	`ux-discovery` · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator	`persona-extractor` · family Planning, Intent Routing & Product Vision
Owner service	WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on	readiness bundle `readiness-bundle-v1` → `RunAccepted` from `RunControlService` when `payload.workflowId == 'ux-discovery'` (event)
Steps	4 · gated 0 · agents 2
Budget per run	400000 tokens · cap 40.0 USD · 180 min
Descriptor	`workflow-definition-v1` · schema
Status	target

Early UX pass on a validated Vision Blueprint: synthesises research, extracts actors, builds personas and seeds journeys and hypotheses as typed artifacts that architecture and the final UX pass read; no blueprint version is produced.

Authored design, Draft (D54, D57)

These definitions were authored from the coordinator cards as design assumptions. None is published, evaluated or has run; agents are named by id as design bindings, not as tested integrations.

Activation (readiness bundle)¶

The Workflow Engine's readiness correlation (BC-38, ADR-0026) joins the signals below per project and bundle fingerprint and submits one run through Run Control's SubmitRun; the run then starts on RunAccepted like every other definition. Nothing starts on a raw event.

Slot	Kind	Descriptor	Required	Satisfied by	Predicate
`vision-blueprint`	blueprint (Vision)	`blueprint-vision-v1`	yes	`BlueprintService.BlueprintValidated`	`payload.kind == 'Vision' and payload.passed == true`
`research`	artifact	`research-insights-v1`	no	`ArtifactService.ArtifactStored`	`payload.descriptor == 'research-insights-v1'`

Consistency: members are satisfied only within the trusted tenant and project of the signal; a newer version of any member opens a new correlation and supersedes the open one
Fingerprint: sha256 over the sorted list of slotversion:hash of every satisfied required and optional member
Idempotency key: {scope}:{operation}:{workflowReleaseId}:{bundleFingerprint}
Deduplication: the same key returns the existing run (SubmitRun: same Idempotency-Key, same canonical body); a new member version yields a new fingerprint and a new correlation, and the Open one is Superseded; a different body under the same key is a 409 and the correlation is Superseded with reason conflict
Submit: workflow ux-discovery (release alias latest), model profile reasoning, input readiness-bundle-v1, client reference correlationId.

Definition¶

flowchart TD
    start(("RunAccepted"))
    synthesize_research["Synthesise research"]
    extract_actors["Extract actors"]
    build_personas["Build personas"]
    seed_journeys["Seed journeys and hypotheses"]
    start --> synthesize_research
    synthesize_research --> extract_actors
    extract_actors --> build_personas
    build_personas --> seed_journeys
    done(("WorkflowRunCompleted"))
    seed_journeys --> done
    classDef gated stroke:#B45309,stroke-width:2px

Hold "Alt" / "Option" to enable pan & zoom

Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine over recorded outputs · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step; a dashed edge is a bounded on_false loop.

Steps¶

#	Step	Kind	Runs	Gate	Class	Depends on	Retry	Timeout	Compensation	What it does
1	Synthesise research `synthesize-research`	agent	`user-researcher` skill `user-researcher-synthesis-with-evidence`	none	read	—	exponential ×3 (30s)	PT30M	—	Plans and synthesises user research for the vision's audiences: sources with classification, insights with evidence and confidence, observations distinguished from hypotheses.
2	Extract actors `extract-actors`	agent	`persona-builder`	none	read	synthesize-research	exponential ×3 (30s)	PT30M	—	Lists the actors and roles the blueprint implies, with their goals and permissions, each citing the insights that evidence it.
3	Build personas `build-personas`	agent	`persona-builder` skill `persona-builder-persona-extraction-and-validation-ux-001`	none	sandbox	extract-actors	exponential ×3 (30s)	PT30M	—	Writes one persona per actor with goals, pain points, empathy map, accessibility needs and locales; the id, name, role, goals and pain points project into the UX Blueprint's Persona shape (UX-001).
4	Seed journeys and hypotheses `seed-journeys`	agent	`persona-builder` skill `persona-builder-journey-seeds-per-persona`	none	sandbox	build-personas	exponential ×3 (30s)	PT30M	—	Seeds one or more journeys per persona (goal, trigger, steps, adverse branches, screen hints) and records the UX hypotheses with their validation plan.

Step contracts¶

Step	Inputs (name ← source)	Outputs (name: descriptor)
`synthesize-research`	`vision-blueprint` ← `input.vision-blueprint` `research-plan` ← `input.research` `feedback` ← `input.research`	`research-insights`: `research-insights-v1`
`extract-actors`	`vision-blueprint` ← `input.vision-blueprint` `research` ← `steps.synthesize-research.research-insights`	`actors`: `artifact-v1`
`build-personas`	`vision-blueprint` ← `input.vision-blueprint` `research` ← `steps.synthesize-research.research-insights` `actors` ← `steps.extract-actors.actors`	`personas`: `personas-v1`
`seed-journeys`	`vision-blueprint` ← `input.vision-blueprint` `research` ← `steps.synthesize-research.research-insights` `actors` ← `steps.extract-actors.actors` `personas` ← `steps.build-personas.personas`	`journey-seeds`: `journey-seeds-v1` `hypotheses`: `ux-hypotheses-v1`
Every mapping names its source (`input.` a workflow input, `steps.` an ancestor's recorded output, `bundle.*` a readiness member) and the validator checks that every required input of the step's agent is mapped and that descriptors agree.

Gates and approvals¶

No approval is required: every step runs in the read or sandbox class; the agents' own tool calls still carry their classes (D21). Compensation steps run in reverse order of the succeeded steps on failure after the last checkpoint; a step without a compensation leaves its sandbox output in place and the run ends Failed with the evidence (ADR-0014, recovery not replay).

Inputs, outputs and events¶

Direction	Name	Descriptor	Required
in	vision-blueprint	`blueprint-vision-v1`	yes
in	research	`research-insights-v1`	no
out	research-insights	`research-insights-v1`	yes
out	personas	`personas-v1`	yes
out	journey-seeds	`journey-seeds-v1`	yes
out	hypotheses	`ux-hypotheses-v1`	yes

Starts on RunAccepted from RunControlService when payload.workflowId == 'ux-discovery'; emits ArtifactStored, plus the engine's WorkflowRunStarted, StepReady, StepRunStateChanged and WorkflowRunCompleted / WorkflowRunFailed and Run Control's run and attempt events (ADR-0014).

Decisions and traceability¶

FR: FR-07 Authorized context assembly with provenance · FR-08 Validated artifacts with lineageFUX: FUX-11 Software Factory journey · FUX-12 Documented viewsADRs: ADR-0014, ADR-0024, ADR-0026 · ADR index

Replaces ux-personas as the early UX pass (ADR-0026, D60); the final pass is ux-blueprint. Draft until an evaluation gate (ADR-0021) and a review publish it as a BC-04 asset release.

Workflow definitions · Workflows catalog · Agent Mesh workflows · Durable execution (ADR-0024) · Approvals