usm/gen-user-docs [planned]

Personas and journey flows (actor/surface per step) become first-class spec data; a new user-doc generator composes task-oriented user guides and Playwright e2e skeletons from persona journeys; help docs for feature pages are composed from persona/journey content instead of filtering developer docs. Backward compatible: flows without persona actors stay pipeline flows in the developer stream. NOTE: flow steps are drafted with actor semantics embedded in action text because the current schema lacks actor/surface — those fields are added by this feature, after which the flows are re-annotated (dogfooding).

Status: planned

Why this exists

Restores the founding vision: the spec holds personas, UI journeys, and e2e-testable flows, so user documentation is COMPOSED from that data (persona guides, task-oriented walkthroughs) while developer docs remain a separate stream. Today's help docs are produced by subtracting developer content from developer docs — the reverse of the vision — and the schema cannot express personas or UI interactions at all. This feature makes personas and journey flows first-class, generates user docs from them, derives Playwright e2e skeletons from the same journeys, and replaces subtraction-based help docs for feature pages with composition.

Design decisions

single-vision-not-staged [accepted]

Decision: Implement the full composition model in one feature — no phased rollout

Rationale: Staged approaches lose intent — the human explicitly rejected phases. Contracts encode the end state (composition replaces subtraction for feature pages), so partial implementations fail review instead of shipping half a vision. Roadmap entries are written in the same session as the spec, not deferred.

minimal-personas [accepted]

Decision: Personas stay minimal: id, name, description — no goals/frustrations/expertise yet

Rationale: Starts authoring via MCP tools without schema bloat; the composition generator only needs identity and context today. Fields can be added additively later without migration.

actor-default-system [accepted]

Decision: Step actor defaults to system; flows without a persona actor remain pipeline flows in developer docs

Rationale: Current flows (parse→generate→write) are genuinely pipeline steps. Making actor optional preserves them untouched and keeps backward compatibility byte-exact.

e2e-link-via-tests [accepted]

Decision: E2E linkage via optional tests[].flow reference — not steps referencing tests

Rationale: Assertions already live in tests[]; a flow reference ties them to journeys without duplicating steps in two places. The journey provides the narrative, the linked tests provide the assertions, one source each.

filter-deprecated-not-deleted [accepted]

Decision: Deprecate (do not delete) the --audience help subtraction filter for feature pages

Rationale: System-level pages (getting started, references) still need filtering; feature pages switch to composition. Keeping the filter functional avoids breaking consumers while the composed path becomes the default for features.

How it works

Author personas and journey flows (author-personas-journeys)

1. Author adds — personas[] to system.usm (id, name, description) — surface: spec
2. Author annotates — flows with actor (flow-level or per-step) and optional surface, marking them as journeys — surface: spec
3. Agent validates — schema: persona ids referenced by actor exist; unknown actors rejected
4. Author reviews — composed user docs rendered live via usm docs serve — surface: browser

Generate user documentation from personas and journeys (generate-user-docs)

1. Agent parses — personas from system.usm, journey flows across all feature specs
2. Agent composes — per-persona guide sections; each journey becomes a task-oriented guide page
3. Agent renders — persona steps as instructions, system/agent steps as 'the system will …' statements
4. Agent writes — user-docs output tree; developer stream untouched

Generate e2e specs from journeys (generate-e2e-specs)

1. Agent selects — journey flows with linked tests[] entries (optional tests[].flow reference)
2. Agent emits — Playwright .spec.ts skeletons per journey under tests/auto-generated/e2e/
3. Agent preserves — existing Vitest generation for non-journey tests

Compose help docs from user content (help-docs-composed)

1. Agent composes — feature pages in help docs from summary, intent, and public journey guides
2. Agent retains — subtraction filter for non-feature (system-level) help pages only
3. Agent deprecates — subtraction path for feature pages, kept functional for one transition cycle

Guarantees

personas-first-class

system.usm gains personas[] — id, name, description. Flows and steps gain optional actor (persona id, or 'system'/'agent') and optional surface (e.g. ui, cli, api).

Acceptance criteria:

• [ ] personas[] validates: unique ids, non-empty name
• [ ] actor values either reference a declared persona id or are system/agent
• [ ] validate fails on unknown persona references (typo protection)
• [ ] existing specs without personas/actor validate unchanged

journeys-vs-pipelines

A flow is a journey when its actor (flow-level or step-level) references a persona; otherwise it is a pipeline and behaves exactly as today.

Acceptance criteria:

• [ ] flows with default (no) actor default to system and stay in the developer stream
• [ ] journeys render in user docs; pipelines never do
• [ ] step-level actor overrides flow-level default

user-docs-composed

New user-doc generator composes guides from personas and journeys — never by filtering developer content.

Acceptance criteria:

• [ ] one guide page per journey: task-oriented title from flow name, ordered steps
• [ ] steps with actor=system/agent rendered as 'the system …' prose, persona steps as instructions
• [ ] per-persona navigation grouping (Guides for <persona>)
• [ ] generation is idempotent and deterministic

e2e-from-journeys

tests[] gains optional flow reference; journey tests emit Playwright e2e skeletons alongside existing Vitest output.

Acceptance criteria:

• [ ] tests with flow referencing a journey emit a valid Playwright .spec.ts under tests/auto-generated/e2e/
• [ ] output path derives from exact feature $id — collision-free (issue #37 class)
• [ ] tests without flow ref continue to generate Vitest specs unchanged

help-composition-replaces-subtraction

Feature pages in help docs are composed from summary, intent, and public journey guides; the subtraction filter is deprecated but stays functional for system-level pages.

Acceptance criteria:

• [ ] help feature pages contain no contracts/tests/implementation sections
• [ ] help feature pages embed the journey guides relevant to public personas
• [ ] existing --audience help still runs and produces a valid site (non-feature pages unchanged)
• [ ] no user-visible regression for projects with no personas defined

backward-compatible

Projects that never declare personas get byte-identical generated output to the previous version.

Acceptance criteria:

• [ ] all existing generators unchanged when no personas/journey actors present
• [ ] schema changes are additive and optional-only
• [ ] existing .usm files validate with no edits required

Test specifications

persona-validation

Given:

• spec_with_flow_actor_referencing_undeclared_persona: true

Then:

• assertion: usm validate rejects unknown persona reference in flow actor
• assertion: usm validate accepts persona id, system, and agent actors

journey-renders-guide

Given:

• feature_with_persona_actor_flow: true

Then:

• assertion: user-docs guide page exists with flow name as task title
• assertion: persona steps rendered as instructions, system steps as system statements
• assertion: developer feature page unchanged in shape and content

pipeline-flows-unchanged

Given:

• feature_with_flows_without_actor: true

Then:

• assertion: no user-docs output for that flow
• assertion: developer doc and Vitest generation identical to pre-change output

e2e-specs-from-journeys

Given:

• journey_with_linked_tests: true

Then:

• assertion: Playwright .spec.ts generated under tests/auto-generated/e2e/ with valid syntax
• assertion: no output path collision between two features defining the same journey id (exact $id parsing, issue #37 class)
• assertion: tests without flow reference still produce Vitest specs only

help-page-composition

Given:

• public_feature_with_journeys: true

Then:

• assertion: help feature page contains journey guide content and no contracts/tests sections
• assertion: help docs build succeeds for a project with zero personas (regression guard)

idempotent-generation

Given:

• generate_run_twice: true

Then:

• assertion: second run produces byte-identical output
• assertion: no orphan files from removed flows

Implementation

• Test code status: none

See Also

• usm/gen-docs-split
• usm/gen-testspecs
• usm/gen-feature-review
• usm/gen-roadmap