A Journey in Catalio is a recorded sequence of steps that captures how a specific user (persona) actually accomplishes a task (JTBD) in a specific version of a software system. Journeys are Catalio’s primary mechanism for evidence-based legacy modernization — replacing subjective assessments with quantified, reproducible user experience data.
Unlike requirements documents that describe what a system should do, journeys document what users actually do. That gap is often where the most valuable discovery happens.
Why Journeys Matter
Legacy modernization projects fail when they rely exclusively on top-down requirements gathering. Stakeholders describe the happy path; engineers document what the spec says. Neither accurately captures the friction, workarounds, and confusion that users encounter daily.
Journeys provide:
- Objective evidence of user experience quality (step counts, duration, friction scores)
- Quantified friction that can be used to build business cases for change
- Traceability — journey steps can be linked to specific Requirements and Capabilities
- Before/after comparison — legacy journeys vs. target journeys prove measurable improvement
Key Fields
| Field | Purpose |
|---|---|
| title | Descriptive name for the journey |
| description | What this journey records and why |
| jtbd_id | The JTBD (Job To Be Done) this journey addresses |
| application_version_id | The Application Version being observed |
| persona_id | The Persona performing the journey |
| capture_method | How the journey was recorded: manual, claude_chrome, playwright |
| status | Journey lifecycle: draft, captured, reviewed, archived |
| captured_at | When the journey capture session completed |
| initiative_id | Optional link to an Initiative |
Journey Lifecycle
draft → captured → reviewed → archived
draft — A capture session has started. Steps are being recorded. The journey is incomplete.
captured — The capture session has ended. All steps are recorded. The journey is ready for review.
reviewed — The journey has been reviewed for accuracy and completeness.
archived — The journey is no longer active but preserved for historical reference.
Capture Methods
Catalio supports three capture methods:
Manual — A human observer records steps by hand, clicking through the system and documenting each action. Best for guided discovery sessions or systems that cannot be automated.
Claude Chrome MCP — Catalio’s AI agent observes a screen recording or live session and automatically records steps, identifies friction points, and suggests step types. This is the fastest capture method for complex workflows.
Playwright — Automated browser scripts run the workflow and record steps programmatically. Best for well-defined, repeatable processes in web applications.
Journey Steps
A Journey is composed of Journey Steps — individual atomic actions that the user performs. Steps capture:
- What the user did (action type: navigation, input, action, wait, error)
- Which screen they were on
- Which UI element they interacted with
- How long the action took
- Whether friction was encountered
See Journey Steps for detailed guidance on step capture and friction classification.
JTBD Linkage
Every Journey is (optionally) linked to a JTBD — the Job To Be Done that motivates the user’s workflow. This link answers: “Why is the user doing this journey?”
The JTBD provides context for interpretation:
- A journey with 47 steps to accomplish “Approve an invoice” signals that friction reduction is the primary opportunity
- A journey linked to a JTBD with high strategic importance rises in modernization priority
Journey Comparisons
Once you have a baseline (legacy) journey and a target (new system) journey for the same JTBD, you can create a Journey Comparison to quantify improvement:
- Step count reduction
- Total duration reduction
- Friction score improvement (high/medium/low friction steps)
These metrics form the quantitative backbone of a modernization business case.
Traceability: Linking Steps to Requirements
Journey Steps can be linked to specific Requirements via RequirementStepLink and to Capabilities via CapabilityStepLink. This creates bottom-up traceability:
Requirement → Implements → Journey Step → Part of → Journey → Covers → JTBD
When a journey step is linked to a requirement, you can trace which requirements are validated by real user behavior — and which requirements have no journey coverage (a gap).
AI-Powered Journey Analysis
Catalio’s AI assists with journey capture and analysis:
- Automatic step detection: During Claude Chrome capture, the AI groups micro-actions into logical steps
- Friction identification: The AI suggests friction levels for steps and generates impact narratives
- Requirement linking: The AI can suggest which requirements each step relates to
- Impact quantification: The AI generates business impact narratives for high-friction steps
Best Practices
Start with the highest-pain JTBD.
Don’t try to capture every journey. Pick the workflows that stakeholders complain about most. High-pain journeys generate the strongest evidence for modernization investment.
Use a consistent persona during capture.
Each journey should represent one persona’s perspective. If multiple user types perform the same workflow differently, capture separate journeys for each.
Capture the messy reality, not the ideal path.
The value of a journey is its accuracy. Include workarounds, error recovery steps, and waiting periods. These are where friction hides.
Link steps to requirements during review.
After capture, go through the journey step by step and link each action to the requirement it validates or exposes. This is time-consuming but creates high-value traceability.
Capture target journeys as early as possible.
Even a mockup or prototype can be journey-captured. The earlier you have target journeys, the earlier you can demonstrate projected improvement.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| JTBD | Journeys are motivated by Jobs To Be Done |
| Application Version | Journeys are captured against a specific version |
| Personas | Journeys represent a specific persona’s behavior |
| Journey Steps | Journeys contain many ordered steps |
| Journey Comparisons | Compare a legacy and target journey |
| Initiative | Journeys can be scoped to an Initiative |
| Requirements | Steps link to Requirements for traceability |
Next Steps
- Define JTBDs — Establish the goals that motivate your journeys
- Capture Journey Steps — Learn the step capture model in detail
- Set Up Application Versions — Anchor journeys to specific system states
- Compare Journeys — Quantify before-and-after improvement
Pro Tip: The most powerful thing you can do with journeys is calculate “friction cost”: multiply the number of high-friction steps by average session frequency by number of users. This turns UX pain into a dollars-per-year number that resonates with executives.
Support
- Documentation: Continue reading about Journey Steps and JTBDs
- In-App Help: The AI journey capture tool walks you through the process
- Email: support@catalio.ai
- Community: Share journey capture techniques with other Catalio users