Catalio logo
Sign in
Banner image for Your First Catalio Workflow
Getting Started • 9 min read

Your First Catalio Workflow

Walk through the ideal onboarding flow: from defining your Application to reviewing AI-surfaced Change Proposals

Updated
On this page

Catalio is a rich platform, and getting oriented can feel like a lot at once. This guide walks you through the ideal first-week flow — a sequence that builds your understanding naturally, where each concept you create becomes the foundation for the next. By the end, you will have a living specification that ties your system’s structure, user needs, and improvement plans into a single coherent picture.

You do not need to complete all of these steps in one session. Catalio is designed to be built up incrementally. What matters is working through them roughly in order, because later steps depend on what you create in earlier ones.

Step 1: Define Your Application

Everything in Catalio starts with an Application — the system you are documenting. An application might be your company’s billing platform, a Salesforce org, a ServiceNow instance, or any custom-built tool. It is the top-level container that holds your features, requirements, journeys, and versions.

Create your application with a clear name and description that will make sense to stakeholders who are not deeply technical. You will refer back to this application throughout every other step in this guide.

If you have multiple systems, start with the one that is most critical or most opaque — the one where the most institutional knowledge is locked up.

Step 2: Map the Application’s Features

Once your application exists, break it down into Features — the major capability areas that the application provides. Features sit between the application and individual requirements: they give you a way to organize dozens or hundreds of requirements into meaningful groups.

Think of features as the top-level sections of a feature list: “Invoicing,” “User Authentication,” “Reporting,” “Data Import.” You do not need to list every feature upfront — add them as you discover them. What matters is that requirements are always attached to a feature, so Catalio can trace policy coverage, component ownership, and initiative scope at the feature level.

Step 3: Capture Requirements

With features in place, start writing Requirements — the specific capabilities each feature must provide. Catalio uses the user story format: As a [persona] I want [capability] so that [benefit].

A few things to know early on:

  • Each requirement must belong to a feature, which in turn belongs to your application. This is how Catalio traces everything back to the system level.
  • Requirements have a lifecycle — they start as drafts and become active once validated. Do not worry about getting them perfect immediately.
  • The AI Grader surfaces quality issues as you write. If a requirement is vague, missing a benefit statement, or ambiguous, the grader will flag it with specific suggestions. Pay attention to these early — well-formed requirements make every downstream step easier.

Aim for a small, high-quality set before expanding. Ten clear, validated requirements are more valuable than fifty vague ones.

Step 4: Identify Personas

A Persona is a named user role or stakeholder type who interacts with your system. Personas are not individual people — they are archetypes like “Finance Manager,” “Field Technician,” or “External Auditor.”

Creating personas before you write more requirements is worthwhile because requirements in Catalio are linked to personas. That linkage lets you ask questions like: “Which requirements affect the Field Technician?” or “Which personas will be impacted by this initiative?” The answers are automatic once the links are in place.

Keep personas concrete and grounded in your actual user base. Avoid generic personas like “User” or “Admin” — the more specific the persona, the more useful the traceability it produces.

Step 5: Write Use Cases

A Use Case describes a specific scenario in which a persona interacts with the system to accomplish a goal. Where a requirement says what the system must do, a use case says how it plays out in practice — including preconditions, happy path steps, alternative flows, and acceptance criteria.

Link each use case to the requirement it validates. This creates a direct chain: Requirement → Use Case → Test Case → Test Result. You can trace from a high-level business need all the way down to “Was this tested? Did it pass?”

You do not need exhaustive use cases for every requirement. Start with the happy path for critical requirements, then add error and edge case scenarios as you have time.

Step 6: Capture Journeys

A Journey is a recorded sequence of steps that a real user takes through the system to accomplish a goal. Journeys are distinct from use cases — they describe what users actually do, not what they should do. This distinction is especially powerful for legacy modernization: journeys expose the friction, workarounds, and inefficiencies baked into the current system.

Journeys are anchored to a specific Application Version, which lets you capture the “before” state of a legacy system and later compare it to the “after” state of a modernized one. Every step in a journey can carry a friction level (none, low, medium, high) and friction notes. High-friction steps are where modernization delivers the most value.

Journey Steps are the atomic units of a journey — individual user actions like navigating to a screen, filling in a field, or waiting for a process to complete.

The AI Classifier can analyze journey steps and suggest friction classifications, saving time when you are capturing journeys from existing screen recordings or SME walkthroughs.

Step 7: Run Discovery Sessions

A Discovery Session is a structured, guided conversation that helps you extract knowledge from subject matter experts. It is the Catalio-native way to bridge the gap between tribal knowledge and formal documentation.

Discovery sessions are linked to initiatives (which you will create shortly), and they guide the conversation through a series of phases: confirming context, deepening persona understanding, walking through workflows, probing for friction, linking findings to requirements, and quantifying impact.

If you have SMEs who know a system deeply but whose knowledge has never been formally captured, discovery sessions are the fastest path from tacit knowledge to structured documentation.

Step 8: Organize Around Capabilities

As your requirements and processes grow, Capabilities provide a way to organize them by business function rather than by system. A capability is a business ability — something the organization can do — rather than a technical feature of a specific application.

Examples: “Invoice Processing,” “Customer Onboarding,” “Compliance Reporting.” Multiple processes and requirements across different applications may all contribute to the same capability.

Processes describe the end-to-end workflows that implement those capabilities. A process might span multiple systems, teams, or personas. Linking processes to requirements and capabilities creates a picture of how business outcomes are produced — which is essential context for modernization planning.

Step 9: Create an Initiative

An Initiative is a scoped modernization effort — the plan to change something, informed by everything you have captured so far. Initiatives move through a governed stage lifecycle: planning → approval → build → release → retro → archived. Each transition is recorded for audit, and readiness signals advise whether the initiative is ready to advance.

When you create an initiative, you can link it to the journeys, requirements, and capabilities it affects. This scope definition is what makes Catalio different from a simple task tracker: the initiative knows what it is changing, which requirements it must satisfy, and which metrics it needs to move.

Onboarding Plans within an initiative provide a structured way to plan the transition for users and teams — ensuring that the people affected by the change are prepared for it.

Initiative Tasks and Initiative Risks let you track the execution detail and uncertainty within each initiative without losing sight of the broader scope.

Step 10: Upload Artifacts

Artifacts are files and documents that provide supporting context for your specification — design mockups, compliance certificates, legacy system exports, meeting transcripts, or any other reference material.

Attaching artifacts to requirements, features, or initiatives keeps all your evidence in one place. But more importantly, when you upload a document, Catalio’s Document Extraction pipeline analyzes it and automatically surfaces Change Proposals — AI-identified gaps, risks, or required changes implied by the document’s content.

Upload an old requirements document, a compliance audit report, or a SME interview transcript and let Catalio do the first pass of extracting what it means for your specification.

Step 11: Review Change Proposals

Change Proposals are AI-generated suggestions for updates to your specification, produced when Catalio analyzes artifacts or detects gaps in your existing documentation. They are the human-in-the-loop review cycle at the heart of Catalio’s AI workflow.

A change proposal might say: “This compliance report implies a new requirement for data retention — do you want to create it?” or “This artifact mentions a persona not currently in your system.”

Review each proposal and accept, modify, or reject it. Accepted proposals create or update records in your specification. Rejected proposals are tracked with a reason, so you have an audit trail of what was considered and why it was declined.

This is where the value of the earlier steps compounds. Because your application, features, requirements, and personas are already defined, Catalio can propose specific, targeted changes rather than generic suggestions.

Step 12: Use AI Chat for Any of the Above

AI Chat is available throughout Catalio and accelerates every step of the workflow above. Rather than navigating menus, you can describe what you want in natural language:

  • “Create a requirement for invoice approval based on the content of the artifact I just uploaded”
  • “Which of our active requirements have no test cases?”
  • “Add a high-friction step to journey J-042 where the user has to re-enter their credentials”
  • “List all requirements linked to the Compliance Auditor persona”

AI Chat understands your organization’s full context — your applications, requirements, journeys, personas, and initiatives. Use it to move faster through the steps in this guide, especially for bulk operations or when you want to query across your specification to find gaps.

Next Steps

You now have a mental model of how Catalio’s pieces fit together. Explore the individual Core Concepts articles to deepen your understanding of each entity:

Support

Need help getting started?