# Jira Add Journey

> 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.

- Skill: `codyswanngt/jira-add-journey` (Agent Skill)
- Install (CLI): `npx skillmds@latest add codyswanngt/jira-add-journey`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codyswanngt/jira-add-journey/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codyswanngt (https://skillmd.com/u/codyswanngt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codyswanngt/jira-add-journey

---


# 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:

```bash
# 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:

```bash
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:

```text
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:

```bash
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