Journeys and improvement

Manual home · Role guides · Coverage · Gaps

Manual conventions and recovery apply to every workflow. Evidence level: code inspected; related tests were inspected, not executed.

flowchart TD
  A[Discovery] --> B[Baseline]
  B --> C[Approved]
  C --> D[Pilot]
  D --> E[Rollout]
  E --> F{Comparable before and after with sufficient samples?}
  F -->|Yes| G[Validated]
  F -->|No| H[Correct or collect evidence]
  H --> F
  G --> I[Closed]
  A --> I
  D --> I

JNY-01 — Configure canonical reasons, troubleshooting processes and actions

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: configure canonical reasons, troubleshooting processes and actions.

Actors and access: qms:read to inspect; molecules:manage for lifecycle mutations.

Prerequisites: Agreed taxonomy/process/action definitions and valid references.

Entry point: Journey configuration.

1. Create/edit draft definitions and validate required links/steps.
2. Publish explicitly; create a revision from a published definition for subsequent changes.
3. Retire published definitions or archive/restore library visibility; permanently delete only eligible drafts.

Result: Published canonical definitions support reproducible analysis while historical versions remain available.

Exceptions and recovery: Published/retired definitions cannot be edited in place. Archived definitions require restore before mutation. Dedicated action-catalogs routes differ from the legacy generic action-catalog alias; see coverage notes.

Source evidence: services/api/src/journey-config/routes.ts; services/api/src/journey-config/validation.ts; apps/web/src/features/journey-config/journey-config.tsx.

JNY-02 — Review AI suggestions for journey configuration items

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: review AI suggestions for journey configuration items.

Actors and access: molecules:manage; configured tenant LLM and usage allowance.

Prerequisites: A supported reason, troubleshooting step or action item.

Entry point: Journey configuration → enrich item.

1. Request enrichment for the selected item.
2. Compare proposed field changes with the current definition and its evidence.
3. Accept/edit selected values into the draft, save deliberately and publish through JNY-01.

Result: Suggestions inform authoring without directly saving the item.

Exceptions and recovery: Unavailable LLM or exhausted usage blocks generation. A suggestion does not create a canonical published path. Review stale/current draft content before applying any edit.

Source evidence: services/api/src/journey-config/routes.ts; packages/contracts/src/journey-config-enrichment.ts; apps/web/src/features/journey-config/journey-config.tsx.

JNY-03 — Approve, merge or dismiss candidate discoveries

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: approve, merge or dismiss candidate discoveries.

Actors and access: qms:read for inspection; molecules:manage for decisions.

Prerequisites: A discovered candidate with source evidence.

Entry point: Journey configuration → Candidates.

1. Inspect the candidate, supporting analyses and match rationale.
2. Approve to create/link a draft, dismiss the candidate, or merge into an existing published canonical target.
3. Inspect the linked draft/target and publish through the normal configuration lifecycle when needed.

Result: A review decision is recorded; approved drafts remain distinct from canonical publication.

Exceptions and recovery: A merge target must be a published tenant definition. Pending-state/idempotency restrictions apply. If draft creation succeeds but linkage fails, retry the supported linking flow instead of creating unrelated duplicates.

Source evidence: services/api/src/candidate-reviews/routes.ts; apps/web/src/features/candidate-reviews/candidate-reviews.tsx; apps/web/src/features/journey-config/journey-config.tsx.

JNY-04 — Inspect journeys, canonical paths and journey analytics

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: inspect journeys, canonical paths and journey analytics.

Actors and access: qms:read at API; local web intelligence gate additionally requires alerts:read.

Prerequisites: Correlated interactions and ready analysis; canonical configuration for classified paths.

Entry point: Journeys dashboard.

1. Choose an ordered date range, channel/team/reason/action and sample filters.
2. Inspect journey outcomes, canonical versus unclassified paths, evidence links and diagnostic rates.
3. Drill into linked interactions and candidate/configuration review to investigate issues.

Result: Evidence-backed paths and analytics describe only their selected cohort.

Exceptions and recovery: Candidates/unmatched actions do not count as canonical path evidence. Sparse cohorts are suppressed according to minimum sample size. Analytics reject reversed or over-365-day ranges; correlation gaps limit claims about complete customer journeys.

Source evidence: services/api/src/journeys/routes.ts; apps/web/src/features/journeys/journeys.tsx; docs/journey-intelligence-rollout.md.

JNY-05 — Create and progress an improvement opportunity

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: create and progress an improvement opportunity.

Actors and access: operations:manage; local intelligence UI access.

Prerequisites: A concrete opportunity, metric, owner/context and source references where available.

Entry point: Journeys → opportunity; Improvements.

1. Create the opportunity in discovery and preserve linked source journey/interaction references.
2. Edit supported descriptive fields and review evidence; capture baseline/pilot measurements using JNY-06.
3. Advance sequentially through discovery, baseline, approved, pilot, rollout and validated, or close deliberately.

Result: A traceable improvement lifecycle records the opportunity and measurements.

Exceptions and recovery: Stage changes use the transition endpoint; source references are immutable. Closed records cannot transition further. Validated requires comparable baseline/pilot evidence and at least five samples in each, including manual evidence.

Source evidence: services/api/src/workspace/routes.ts; apps/web/src/features/operations/operations.tsx.

JNY-06 — Capture comparable baseline and pilot measurements

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: capture comparable baseline and pilot measurements.

Actors and access: operations:manage.

Prerequisites: An improvement metric and a fixed comparison cohort.

Entry point: Improvements → Review evidence and capture results.

1. Select before/after phase, source, metric, cohort and ordered time windows.
2. Calculate from journeys or enter manager-measured value, sample count, rationale and evidence reference.
3. Save both measurements and inspect sample counts before requesting validation.

Result: Measurements explicitly identify calculated versus manager-entered provenance.

Exceptions and recovery: Both phases require the same metric/cohort/source and equal-duration non-overlapping windows in order. Insufficient samples block validation. A manually entered result is labelled as such and does not become a system-calculated outcome.

Source evidence: services/api/src/workspace/routes.ts; packages/contracts/src/operations.ts; apps/web/src/features/operations/operations.tsx.

JNY-07 — Review journey-informed coaching suggestions

Status: Feature-gated. Verification: code inspected; no runtime completion claim.

Purpose: review journey-informed coaching suggestions.

Actors and access: operations:manage; tenant journey-coaching gate enabled by owner.

Prerequisites: Rollout gates passed; canonical evidence with at least five journeys in a cohort.

Entry point: Journeys → coaching suggestions.

1. Inspect cohort, sample size, failed steps/actions, interaction evidence and relevant knowledge/training.
2. Choose an eligible agent and review a suggested coaching/training action.
3. Explicitly accept into the existing coaching/training flow; review the resulting draft/assignment before further lifecycle actions.

Result: Manager-approved follow-up connects canonical journey evidence to improvement work.

Exceptions and recovery: The gate defaults disabled. Candidate/unmatched evidence is excluded; low sample cohorts produce no suggestion. No plan/training assignment should be described as automatic.

Source evidence: services/api/src/journeys/routes.ts; apps/web/src/features/journeys/journeys.tsx; docs/journey-intelligence-rollout.md.

JNY-08 — Record and inspect correlated survey responses

Status: Incomplete. Verification: code inspected; no runtime completion claim.

Purpose: record and inspect correlated survey responses.

Actors and access: integrations:manage for generic survey records; local UI also has navigation/access constraints.

Prerequisites: A supported survey payload with trusted correlation and timestamps.

Entry point: Surveys preview; generic surveys API.

1. Ingest/create supported response records through the authorised integration/API process.
2. Inspect available survey entries and their correlation to interactions/journeys.
3. Use survey-derived metrics only within the matching cohort and time window.

Result: Survey records can contribute outcome evidence to supported metrics.

Exceptions and recovery: The preview does not establish a survey designer, public response collector or automated distribution workflow. Missing correlation prevents reliable linkage; record those limits rather than inventing an end-user survey flow.

Source evidence: services/api/src/workspace/routes.ts; packages/contracts/src/operations.ts; apps/web/src/features/operations/operations.tsx.