jira-add-journey

name	jira-add-journey
description	Add a Validation Journey section to an existing JIRA ticket by reading the ticket description, understanding the feature, and generating the journey steps, viewports, and assertions.

Add Validation Journey to Existing JIRA Ticket

Read an existing JIRA ticket, understand the feature or fix it describes, analyze the codebase to determine the user flow, and append a Validation Journey section to the ticket description.

Arguments

$ARGUMENTS: <TICKET_ID>

• TICKET_ID (required): JIRA ticket key (e.g., PROJ-123)

Prerequisites

• JIRA_API_TOKEN environment variable set
• jira-cli configured. Prefer the config Lisa writes at .lisa/jira-cli/.config.yml (the setup-jira-cli SessionStart hook writes it from JIRA_SERVER / JIRA_LOGIN / JIRA_PROJECT on a project whose tracker is jira), and pass it explicitly with --config. A developer's own ~/.config/.jira/.config.yml still works as jira-cli's default when no --config is given.

Workflow

Step 1: Read the Ticket

Use the Atlassian MCP or jira-cli to read the full ticket details:

# Run from the project root. --config pins jira-cli to the file Lisa's
# setup-jira-cli hook wrote, instead of the machine's own ~/.config/.jira.
# jira-cli resolves --config > JIRA_CONFIG_FILE > ~/.config/.jira/.config.yml,
# and a --config path that does not exist fails closed with "Missing
# configuration file." rather than silently using the default.
jira --config .lisa/jira-cli/.config.yml issue view <TICKET_ID>

If .lisa/jira-cli/.config.yml does not exist, drop --config to fall back to the machine's own jira-cli config — but say so in your report rather than letting the Lisa-written config go quietly unused.

Extract:

• Title and description (what the feature/fix is)
• Acceptance criteria (what needs to be verified)
• Components or labels (frontend, mobile, responsive, etc.)
• Any linked tickets or parent epic context

Step 2: Check for Existing Journey

Run the parser to see if a Validation Journey already exists:

python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID> 2>&1

If the parser succeeds and returns steps, the ticket already has a journey. Report this to the user and stop.

Step 3: Analyze the Feature

Based on the ticket description and acceptance criteria:

1. Identify the UI surface — Which pages, modals, or components are affected?
2. Identify the user flow — What steps does a user take to exercise the feature?
3. Identify visual checkpoints — At which states should screenshots be captured?
4. Identify viewports — Does this feature have responsive behavior? Always include Desktop. Add Mobile for responsive changes.
5. Identify assertions — What must be visually true for the feature to be correct?

Use the Explore agent or read the codebase directly to understand:

• Which components are involved (search by ticket ID, feature name, or file paths mentioned in the ticket)
• What testIDs exist (for Playwright interaction)
• What the user flow looks like (Container/View structure, navigation, modals)

Step 4: Draft the Validation Journey

Compose the journey following the format:

h2. Validation Journey

h3. Prerequisites
- List what must be true before starting (backend, auth, feature flags)

h3. Steps
1. First action the user takes
2. Second action [SCREENSHOT: descriptive-name]
3. Continue the flow
4. Final verification [SCREENSHOT: final-state]

h3. Viewports
||Name||Width||Height||
|Desktop|1512|768|
|Mobile|375|812|

h3. Assertions
- Testable visual statement about the expected behavior
- Another assertion about responsive layout

Guidelines for Drafting

1. 3-7 screenshot markers — Enough to prove the feature, not so many that execution is slow
2. Concrete steps — "Click the 'Add action' button" not "Interact with the controls"
3. Include auth if needed — If the journey requires login, include credentials in Prerequisites
4. Name feature flags explicitly — If the feature is behind a PostHog flag, name it
5. Assertions must be testable — "Buttons stacked vertically on mobile" not "Layout looks good"
6. Screenshot names in kebab-case — confirm-step-disabled, modal-open, form-error

Step 5: Present to User for Approval

Display the drafted Validation Journey to the user and ask for confirmation before appending it to the ticket. The user may want to:

• Add or remove steps
• Change screenshot markers
• Adjust viewports or assertions
• Modify prerequisites

Step 6: Append to Ticket Description

After user approval, use the JIRA REST API to append the Validation Journey to the existing ticket description.

Use the Atlassian MCP updateJiraIssue to update the description field. The journey section must be appended after the existing description content, not replace it.

Step 7: Verify

Run the parser again to confirm the journey was added correctly:

python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>

The parser should now return the steps, viewports, and assertions from the newly added section.

When to Use This Skill

• Ticket was created before the Validation Journey convention was established
• Ticket was created manually without following lisa:jira-create guidelines
• Ticket needs a journey added or updated based on implementation progress
• During sprint planning, to ensure all frontend tickets have journeys before work starts