kb-journeys

Skill: KB Journeys

Journeys describe how a persona moves through a product, service, or process — as a hierarchy (journey → phase → sub-journey → step) with explicit entry conditions, exit conditions, cross-journey interfaces, and readiness assessments per visible step. They are a first-class product-management KB artifact, separate from roadmaps (plan↔delivery) and topics (positions), but tightly coupled to both as the product-behavior reference layer.

This skill turns markdown journey specs into:

1. A browsable HTML set (one HTML per journey + an index) that respects the adopter's brand tokens.
2. An automatic standalone-mock index — every embedded UI or terminal mock is also rendered as its own page and back-linked.
3. A four-command authoring arc shared with kb-roadmap: ideate, discuss, review, refine.

When to invoke

Invoke whenever the user:

• Types /kb journeys (optionally followed by new, render, extract-mocks, audit, ideate, discuss, review, refine).
• Describes a user flow, a phase map, an onboarding path, an incident response path, or any multi-step persona-centric narrative.
• Asks "how does a user / customer / operator move through X?".

Why journeys matter in the operating model

Journeys are the cleanest shared answer to: what is the thing supposed to do for whom, through which path, at what level of readiness?

That makes them the bridge between:

• joint roadmap intent — what leadership/product says should move
• workstream detail reality — what engineering is actually building, learning, changing, and proving

Roadmap items should move journey readiness. Delivery updates should be explainable in journey terms. Scope changes should be visible as changes in journey shape, step priority, or readiness movement, not only as ticket churn.

Core rules (always apply)

1. Markdown is the source of truth. HTML is generated; never hand-edit the HTML.
2. Every journey is self-contained. Readable without loading any other journey, but with explicit ## Interfaces to adjacent journeys.
3. Every visible step has a stable id (J<journey>.<phase>-S<step>, e.g. J1.1-S3). Ids do not change once assigned — they are link targets across the KB.
4. Every visible step carries a readiness chip — green / amber / red, with a one-line rationale. Journeys without readiness are draft only.
5. Every embedded mock is extractable — wrap in the mock envelope so the extractor can lift it out into a standalone page.
6. Zero vendor strings. Brand colors, fonts, logos come from the adopter's .kb-config/artifacts.yaml. The skill's template ships with neutral tokens.
7. Dual output always. Every render run emits the per-journey HTMLs + the mocks index in the same pass. They never drift.
8. Journeys are ground truth for the roadmap. When a scope in kb-roadmap declares journey-refs pointing here, every roadmap item is cross-checked against its cited step(s). Journey steps are the definition of what the product must do; roadmap items exist to move step readiness forward. A journey is never silently updated from roadmap findings — drift findings trigger /kb journeys review <step>, which is a deliberate authoring pass.
9. Journeys must work both top-down and bottom-up. Top-down: strategy or roadmap intent can introduce or re-prioritize a journey or step. Bottom-up: engineering discoveries, demo feedback, prototype learning, and customer signal can force a journey refinement, split, merge, or readiness downgrade.
10. Daily work should feed journeys with intent, not noise. Not every ticket touches a journey, but every meaningful product behavior change should be able to point to the step it advances, challenges, or invalidates.
11. Log every run to .kb-log/YYYY-MM-DD.log.
12. Setup decides ownership. /kb setup proposes the owning layer from the user's role, audience, sources, and desired outputs. The conservative default is to co-locate journeys with the roadmap scope they ground. Cross-layer journey inheritance is allowed by the layer graph but treated as a later enhancement unless the user explicitly configures it.
13. Journey text stays value-oriented. Step titles describe what the persona can do, learn, decide, or recover from; implementation mechanics belong in step detail, interfaces, or readiness notes.