git:20260718.7cc9d66 to git:20260718.206351f

11 added, 35 removed. Audit A to A.

---

name: critical-journey-document

- description: Create concise Markdown documentation for critical user journeys, flows, acceptance scenarios, service blueprints, telemetry, portfolios, story maps, and coverage. Use when product behavior needs traceable docs-as-code tied to evidence and ownership.

+ description: Create one concise evidence-linked product journey record for one actor pursuing one goal. Use when product behavior needs traceable ownership, acceptance, telemetry, or service-flow documentation for a current decision or delivery gate.

---

# Critical Journey Documentation

- Document one actor pursuing one goal. Use structured Markdown and only the artifacts needed for the current decision or delivery gate.

- ## Core Model

- - Journey ID: `JRN.<domain>.<goal>.<optional-channel>.<optional-variant>`

- - Scenario ID: `SCN.<domain>.<goal>.<case>`

- - Event: `<domain>_<object>_<action>`

- - Status: `draft`, `review`, `active`, or `deprecated`

- - Risk: `low`, `medium`, `high`, or `critical`

- - Missing evidence: `TBD(owner)`

- ## Artifact Selection

- Create the smallest useful set under the repository's established documentation path:

- - **Brief:** actor, goal, scope, trigger, preconditions, success, failure, owner, risk, and evidence links.

- - **Flow:** ordered touchpoints, decisions, state changes, failure paths, recovery, and accessibility behavior.

- - **Acceptance:** named Given/When/Then scenarios for success, failure, recovery, permissions, and accessibility.

- - **Telemetry:** funnel steps, event contracts, required properties, privacy constraints, metrics, thresholds, and dashboard ownership.

- - **Blueprint:** frontstage, backstage, support systems, handoffs, operational risks, and recovery; add only for cross-team or operationally risky journeys.

- - **Portfolio, coverage, or story map:** add only when coordinating multiple journeys, release evidence, or sequencing.

+ Create one canonical journey record in the repository's established product-documentation location.

## Workflow

- 1. Identify actor, goal, domain, channel, risk, and owner.

- 2. Inspect existing requirements, code, contracts, tests, telemetry, and documentation.

- 3. Split multiple actors or goals into separate journeys.

- 4. Create or update only the necessary artifacts.

- 5. Link claims to existing requirements, contracts, tests, dashboards, and evidence.

- 6. Mark unsupported facts as `TBD(owner)` rather than inventing them.

- 7. Run the repository's Markdown formatter when available.

+ 1. Confirm what makes the journey critical, its actor, goal, trigger, scope, owner, risk, and canonical document location.

+ 2. Inspect existing requirements, code, contracts, tests, telemetry, and documentation; reuse repository identifiers and terminology.

+ 3. Split multiple actors or goals into separate records only when independently useful.

+ 4. Document the ordered journey, decisions, state changes, success, meaningful failures, recovery, ownership, and evidence links.

+ 5. Add acceptance, telemetry, blueprint, portfolio, coverage, or story-map sections only when a named consumer or delivery gate requires them.

+ 6. Record unresolved facts only when the task permits them and names the decision owner and resolution condition.

- ## Guardrails

+ Acceptance sections describe product acceptance; `test-design` owns executable tests. Telemetry sections record agreed contracts rather than inventing events. `repo-context-document` owns implemented-system flows under `docs/context/`; `rollout-readiness-review` owns deployment readiness; `spec-update` owns semantic decisions.

- - Keep files concise and Git-tracked.

- - Prefer tables, bullets, checklists, IDs, and small Mermaid diagrams over prose.

- - Do not create posterware, unsupported claims, duplicate documentation, or an entire artifact suite by default.

- - Do not treat visual design tools as canonical; link to them.

+ Do not create a parallel canonical document, mandatory identifier system, speculative telemetry, or an artifact suite by default.

- Finish when the chosen artifacts provide enough traceability to design, implement, validate, release, or operate the journey.

+ Finish when the record has evidence links, named ownership, explicit unknowns, and only sections with current consumers.