@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/expo/skills/jira-add-journey/SKILL.md

@@ -0,0 +1,126 @@
+---
+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 (`~/.config/.jira/.config.yml`)
+
+## Workflow
+
+### Step 1: Read the Ticket
+
+Use the Atlassian MCP or jira-cli to read the full ticket details:
+
+```bash
+jira issue view <TICKET_ID>
+```
+
+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 `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

package/plugins/src/expo/skills/jira-create/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: jira-create
+description: This skill should be used when creating JIRA epics, stories, and tasks from code files or descriptions. It analyzes the provided input, determines the appropriate issue hierarchy, and creates issues with comprehensive quality requirements including test-first development and documentation.
+allowed-tools: ["Read", "Glob", "LS", "mcp__atlassian__createJiraIssue", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Create JIRA Issues from $ARGUMENTS
+
+Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all mandatory quality gates.
+
+## Process
+
+1. **Analyze**: Read $ARGUMENTS to understand scope
+2. **Determine Structure**:
+   - Epic needed if: multiple features, major changes, >3 related files
+   - Direct tasks if: bug fix, single file, minor change
+3. **Create Issues** with hierarchy:
+   ```
+   Epic → User Story → Tasks (test, implement, document, cleanup)
+   ```
+
+## Mandatory for Every Code Issue
+
+**Test-First**: Write tests before implementation
+**Quality Gates**: All tests/checks must pass, no SonarCloud violations
+**Documentation**: Check existing, update/create new, remove obsolete
+**Feature Flags**: All features behind flags with lifecycle plan
+**Cleanup**: Remove temporary code, scripts, dev configs
+**Validation Journey**: Every ticket that touches UI must include a Validation Journey section (see below)
+
+## Validation Journey (Frontend Tickets)
+
+Every ticket that changes, adds, or fixes UI must include a `Validation Journey` section in the description. This section is consumed by the `jira-journey` skill to automate visual verification via Playwright.
+
+### When to Include
+
+Include a Validation Journey when the ticket involves:
+- New UI components or screens
+- Layout or styling changes (responsive, spacing, colors)
+- Modal, drawer, or popover behavior
+- Form validation or user input flows
+- Bug fixes that are visually verifiable
+
+Skip the Validation Journey only for:
+- Pure backend/API changes with no UI surface
+- Config-only changes (env vars, feature flags)
+- Test-only or documentation-only changes
+
+### How to Write
+
+Design the journey from the **end user's perspective**. Walk through the exact steps a human would take to verify the change. Place `[SCREENSHOT: name]` markers at the key visual checkpoints.
+
+Add this section to the ticket description:
+
+```text
+h2. Validation Journey
+
+h3. Prerequisites
+- App running locally or on dev
+- Authenticated as test user
+- Any required feature flags enabled
+
+h3. Steps
+1. Navigate to the relevant page
+2. Perform the first action
+3. Verify the expected state [SCREENSHOT: state-name]
+4. Perform the next action
+5. Verify the final state [SCREENSHOT: final-state]
+
+h3. Viewports
+||Name||Width||Height||
+|Desktop|1512|768|
+|Mobile|375|812|
+
+h3. Assertions
+- Describe what must be visually true at each viewport
+- Each assertion is verified against the captured screenshots
+```
+
+### Guidelines
+
+1. **Steps must be concrete and executable** — "Navigate to Players page" not "Go to the relevant section"
+2. **Screenshot markers at visual checkpoints** — Place `[SCREENSHOT: name]` at states that prove the change works. Use descriptive kebab-case names (e.g., `modal-open`, `button-disabled`, `form-error`)
+3. **Include 3-7 screenshot markers** — Enough to prove the feature works, not so many that execution is slow
+4. **Viewports match the change scope** — Always include Desktop (1512x768). Add Mobile (375x812) for responsive changes. Add Tablet (768x1024) only if relevant.
+5. **Assertions are testable statements** — "Buttons stacked vertically on mobile" not "Layout looks good"
+6. **Prerequisites include feature flags** — If the feature is behind a PostHog flag, name it explicitly
+7. **Auth steps included when needed** — If the journey requires login, include the test credentials in Prerequisites
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default project: from jira-cli config (override via arguments)
+Exclude unless requested: migration plans, performance tests
+
+Execute the analysis and create the complete JIRA structure with proper parent-child relationships.

package/plugins/src/expo/skills/jira-evidence/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: jira-evidence
+description: "Upload screenshots to GitHub pr-assets release, update PR description with evidence, upload attachments to JIRA, post wiki markup comment, and move ticket to Code Review. Reusable by any skill that captures screenshots and generates evidence/comment.txt + evidence/comment.md."
+---
+
+# JIRA Evidence Posting
+
+Upload captured screenshots and generated templates to GitHub PR description and JIRA ticket. This skill is the posting step — it assumes screenshots and comment templates already exist in the evidence directory.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `EVIDENCE_DIR` (required): Directory containing screenshots and templates (e.g., `./evidence`)
+- `PR_NUMBER` (required): GitHub PR number to update description
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`) — server and login are read from there
+- `gh` CLI authenticated
+- Evidence directory containing:
+  - `NN-name-viewport.png` screenshots (numbered, e.g., `01-search-step-desktop.png`)
+  - `comment.txt` — JIRA wiki markup (generated by `generate-templates.py`)
+  - `comment.md` — GitHub markdown (generated by `generate-templates.py`)
+
+## Usage
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+```
+
+### Example
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh PROJ-123 ./evidence 42
+```
+
+## What It Does
+
+1. **Read JIRA config** — Reads `~/.config/.jira/.config.yml` to obtain `server` and `login` dynamically (no hardcoded values)
+2. **Upload to GitHub `pr-assets` release** — Uploads `NN-name-viewport.png` screenshots via `gh release upload --clobber`, creating CDN URLs that render in GitHub markdown
+3. **Update PR description** — Replaces or appends the `## Evidence` section in the PR body using `gh pr edit`
+4. **Upload JIRA attachments** — Uploads screenshots via REST API v3 so `!filename.png!` wiki markup renders inline
+5. **Post JIRA comment** — Posts `comment.txt` as a new comment via REST API v2 (wiki markup with embedded images)
+6. **Move ticket to Code Review** — Transitions the JIRA ticket via `jira issue move`
+
+## Screenshot Naming Convention
+
+Only files matching `NN-*.png` (two-digit prefix) are uploaded. Other files in the evidence directory are ignored.
+
+```text
+evidence/
+  01-search-step-desktop.png    ✓ uploaded
+  02-confirm-step-desktop.png   ✓ uploaded
+  03-search-step-mobile.png     ✓ uploaded
+  comment.txt                   used for JIRA comment
+  comment.md                    used for PR description
+```
+
+## Troubleshooting
+
+### Images not rendering in GitHub PR
+
+Images must be in the `pr-assets` GitHub release (not committed to git). The script handles this via `gh release upload`. If the release does not exist, create it first:
+
+```bash
+gh release create pr-assets --title "PR Assets" --notes "CDN for PR evidence screenshots"
+```
+
+### JIRA comment shows `!filename.png!` as text (not image)
+
+The screenshot must be uploaded as a JIRA attachment before posting the comment. The script uploads attachments first then posts the comment — always in that order.
+
+### JIRA API returns 403 on attachment upload
+
+Ensure `JIRA_API_TOKEN` is set and `login` in `~/.config/.jira/.config.yml` matches your Atlassian account email.

package/plugins/src/expo/skills/jira-evidence/scripts/post-evidence.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# post-evidence.sh — Upload evidence and post to JIRA + GitHub PR description
+#
+# Usage:
+#   bash post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+#
+# Prerequisites:
+#   - JIRA_API_TOKEN env var set
+#   - jira-cli configured (~/.config/.jira/.config.yml)
+#   - gh CLI authenticated
+#
+# What it does:
+#   1. Uploads evidence files to the 'pr-assets' GitHub release
+#   2. Updates the GitHub PR description with evidence/comment.md
+#   3. Uploads image evidence as JIRA attachments
+#   4. Posts/updates the JIRA comment with evidence/comment.txt
+#   5. Moves the JIRA ticket to "Code Review"
+
+set -euo pipefail
+
+TICKET_ID="${1:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+EVIDENCE_DIR="${2:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+PR_NUMBER="${3:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+
+JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+if [[ ! -f "$JIRA_CONFIG" ]]; then
+  echo "ERROR: jira-cli config not found at $JIRA_CONFIG — run 'jira init' first" >&2
+  exit 1
+fi
+JIRA_SERVER=$(grep '^server:' "$JIRA_CONFIG" | awk '{print $2}')
+JIRA_USER=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+GH_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+RELEASE_TAG="pr-assets"
+
+if [[ -z "${JIRA_API_TOKEN:-}" ]]; then
+  echo "ERROR: JIRA_API_TOKEN environment variable is not set" >&2
+  exit 1
+fi
+
+# Collect numbered evidence files (images + text)
+SCREENSHOTS=()
+while IFS= read -r -d '' f; do
+  SCREENSHOTS+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 -name '[0-9][0-9]-*.png' -print0 | sort -z)
+
+TEXT_EVIDENCE=()
+while IFS= read -r -d '' f; do
+  TEXT_EVIDENCE+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 \( -name '[0-9][0-9]-*.txt' -o -name '[0-9][0-9]-*.json' \) ! -name 'comment.txt' -print0 | sort -z)
+
+ALL_EVIDENCE=("${SCREENSHOTS[@]}" "${TEXT_EVIDENCE[@]}")
+
+if [[ ${#ALL_EVIDENCE[@]} -eq 0 ]]; then
+  echo "ERROR: No numbered evidence files found in $EVIDENCE_DIR (expected NN-*.png, NN-*.txt, or NN-*.json)" >&2
+  exit 1
+fi
+
+echo "Found ${#SCREENSHOTS[@]} screenshots and ${#TEXT_EVIDENCE[@]} text evidence files to upload"
+
+# Compute JIRA auth early (used in steps 3 and 4)
+JIRA_AUTH=$(echo -n "$JIRA_USER:$JIRA_API_TOKEN" | base64)
+
+# ── Step 1: Upload to GitHub pr-assets release ──────────────────────────────
+echo ""
+echo "==> Uploading to GitHub release '$RELEASE_TAG'..."
+
+for FILE in "${ALL_EVIDENCE[@]}"; do
+  FILENAME=$(basename "$FILE")
+  echo "  ↑ $FILENAME"
+  gh release upload "$RELEASE_TAG" "$FILE" --repo "$GH_REPO" --clobber
+done
+
+echo "  ✓ GitHub release assets uploaded"
+
+# ── Step 2: Update GitHub PR description with evidence ──────────────────────
+COMMENT_MD="$EVIDENCE_DIR/comment.md"
+if [[ ! -f "$COMMENT_MD" ]]; then
+  echo "ERROR: $COMMENT_MD not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Updating GitHub PR #$PR_NUMBER description..."
+
+CURRENT_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+
+# Replace or append the Evidence section
+if echo "$CURRENT_BODY" | grep -q "^## Evidence"; then
+  # Replace from "## Evidence" to end of file
+  NEW_BODY=$(echo "$CURRENT_BODY" | sed '/^## Evidence/,$d')
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${NEW_BODY}
+${EVIDENCE_SECTION}"
+else
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${CURRENT_BODY}
+
+${EVIDENCE_SECTION}"
+fi
+
+gh pr edit "$PR_NUMBER" --body "$UPDATED_BODY"
+echo "  ✓ PR description updated with evidence"
+
+# ── Step 3: Upload image evidence as JIRA attachments ───────────────────────
+if [[ ${#SCREENSHOTS[@]} -gt 0 ]]; then
+  echo ""
+  echo "==> Uploading image attachments to JIRA $TICKET_ID..."
+
+  for IMG in "${SCREENSHOTS[@]}"; do
+    FILENAME=$(basename "$IMG")
+    echo "  ↑ $FILENAME"
+    RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+      -X POST \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "X-Atlassian-Token: no-check" \
+      -F "file=@$IMG" \
+      "$JIRA_SERVER/rest/api/3/issue/$TICKET_ID/attachments")
+    HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+    if [[ "$HTTP_CODE" != "200" ]]; then
+      echo "  WARNING: Failed to upload $FILENAME (HTTP $HTTP_CODE)" >&2
+    fi
+  done
+
+  echo "  ✓ JIRA attachments uploaded"
+fi
+
+# ── Step 4: Post JIRA comment ────────────────────────────────────────────────
+COMMENT_TXT="$EVIDENCE_DIR/comment.txt"
+if [[ ! -f "$COMMENT_TXT" ]]; then
+  echo "ERROR: $COMMENT_TXT not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Posting JIRA comment on $TICKET_ID..."
+
+COMMENT_BODY=$(cat "$COMMENT_TXT")
+COMMENT_JSON=$(python3 -c "import sys, json; print(json.dumps(sys.stdin.read()))" <<< "$COMMENT_BODY")
+
+RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+  -X POST \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Content-Type: application/json" \
+  "$JIRA_SERVER/rest/api/2/issue/$TICKET_ID/comment" \
+  -d "{\"body\": $COMMENT_JSON}")
+HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+
+if [[ "$HTTP_CODE" == "201" ]]; then
+  echo "  ✓ JIRA comment posted"
+else
+  echo "  WARNING: JIRA comment returned HTTP $HTTP_CODE" >&2
+  echo "$RESP" | grep -v "HTTP_CODE:" | head -3
+fi
+
+# ── Step 5: Move ticket to Code Review ──────────────────────────────────────
+echo ""
+echo "==> Moving $TICKET_ID to Code Review..."
+jira issue move "$TICKET_ID" "Code Review" 2>&1 && echo "  ✓ Ticket moved to Code Review" || echo "  WARNING: Could not move ticket" >&2
+
+echo ""
+echo "==> Done!"
+echo "    JIRA:   $JIRA_SERVER/browse/$TICKET_ID"
+echo "    GitHub: https://github.com/$GH_REPO/pull/$PR_NUMBER"

package/plugins/src/expo/skills/jira-journey/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: jira-journey
+description: "Read a JIRA ticket's Validation Journey section, execute the steps using Playwright MCP browser tools across all defined viewports, capture screenshots at each marker, generate evidence templates, and post to JIRA + GitHub PR using the jira-evidence skill."
+---
+
+# JIRA Validation Journey
+
+Read a JIRA ticket's Validation Journey, execute it via Playwright MCP browser tools, capture screenshots at every `[SCREENSHOT: name]` marker across all viewports, and post evidence to both JIRA and GitHub PR.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> [PR_NUMBER]`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `PR_NUMBER` (optional): GitHub PR number to update description
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`)
+- `gh` CLI authenticated
+- Playwright MCP server running (browser tools available)
+- Dev server running
+
+## Workflow
+
+### Step 1: Parse the Validation Journey
+
+Run the parser script to extract the Validation Journey from the JIRA ticket description:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>
+```
+
+The script outputs JSON to stdout:
+
+```json
+{
+  "ticket": "PROJ-123",
+  "prerequisites": [
+    "Backend dev server running",
+    "Admin user with test credentials"
+  ],
+  "steps": [
+    {"number": 1, "text": "Navigate to Players page", "screenshot": null},
+    {"number": 5, "text": "Open transfer modal", "screenshot": "confirm-step-disabled"}
+  ],
+  "viewports": [
+    {"name": "Desktop", "width": 1512, "height": 768},
+    {"name": "Mobile", "width": 375, "height": 812}
+  ],
+  "assertions": [
+    "Modal fills entire screen on mobile (no horizontal overflow)"
+  ]
+}
+```
+
+Read the JSON output and use it to drive the Playwright session.
+
+### Step 2: Satisfy Prerequisites
+
+Before starting the journey, verify each prerequisite:
+
+1. Check if the dev server is running (try `browser_navigate` to the app URL)
+2. Authenticate if needed (use test credentials from `.env.localhost` or `.env.local`)
+3. Navigate to the starting point described in step 1
+
+### Step 3: Execute Steps at Each Viewport
+
+For **each viewport** defined in the journey:
+
+1. Use `browser_resize` to set the viewport dimensions
+2. Execute each step sequentially using Playwright MCP tools
+3. At each step with a `screenshot` marker, use `browser_take_screenshot` to capture the screenshot
+
+#### Screenshot Naming Convention
+
+Screenshots are named: `{NN}-{screenshot-name}-{viewport-name}.png`
+
+- `NN`: zero-padded sequential number (01, 02, 03...)
+- `screenshot-name`: the value from `[SCREENSHOT: name]` in the JIRA step
+- `viewport-name`: lowercase viewport name from the Viewports table
+
+Example: For a journey with 3 screenshot markers and 2 viewports:
+
+```text
+evidence/
+  01-search-step-desktop.png
+  02-confirm-step-desktop.png
+  03-success-step-desktop.png
+  04-search-step-mobile.png
+  05-confirm-step-mobile.png
+  06-success-step-mobile.png
+  comment.txt
+  comment.md
+```
+
+#### Viewport Execution Strategy
+
+Execute the **full journey once per viewport**. Between viewports:
+
+1. Resize the browser using `browser_resize`
+2. Navigate back to the starting point
+3. Re-execute all steps from the beginning
+
+This ensures each screenshot is captured at the correct viewport dimensions with the correct application state.
+
+### Step 4: Generate Evidence Templates
+
+After capturing all screenshots, run the template generator:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/generate-templates.py \
+  <TICKET_ID> \
+  <PR_NUMBER> \
+  <BRANCH_NAME> \
+  ./evidence
+```
+
+This generates `evidence/comment.txt` (JIRA wiki markup) and `evidence/comment.md` (GitHub markdown) with:
+
+- PR and branch metadata
+- All screenshots organized by viewport
+- The verification journey steps
+- Assertions as verification results
+
+### Step 5: Post Evidence
+
+Use the jira-evidence skill to post everything:
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> ./evidence <PR_NUMBER>
+```
+
+### Step 6: Verify
+
+Confirm images render inline at both the JIRA ticket and GitHub PR.
+
+## Validation Journey Format in JIRA
+
+The JIRA ticket description must contain a section with this structure:
+
+### ADF Structure
+
+```text
+h2. Validation Journey
+
+h3. Prerequisites
+- App running locally or on dev
+- Authenticated as test user
+- Required feature flags enabled
+
+h3. Steps
+1. Navigate to the relevant page
+2. Perform the first action
+3. Click on the element [SCREENSHOT: element-state]
+4. Complete the flow
+5. Verify the final state [SCREENSHOT: final-state]
+
+h3. Viewports
+||Name||Width||Height||
+|Desktop|1512|768|
+|Mobile|375|812|
+
+h3. Assertions
+- Visual assertion about expected behavior
+- Another assertion about responsive layout
+```
+
+### Key Rules
+
+1. **`[SCREENSHOT: name]`** markers define where to capture. The `name` is used in the filename.
+2. **Steps without markers** are executed but not captured.
+3. **Viewports** define all resolutions to test. Each viewport runs the full journey.
+4. **Assertions** describe what to verify visually in each screenshot.
+5. **Prerequisites** describe what must be true before starting.
+
+## Troubleshooting
+
+### Modal closes on viewport resize
+
+Some modals close when the viewport changes. The viewport execution strategy (full journey per viewport) handles this — each viewport starts fresh.
+
+### Authentication required at each viewport
+
+If the app requires re-authentication after resize/navigation, include the auth steps in the journey.
+
+### Screenshot markers in conditional steps
+
+If a step is conditional, capture the screenshot at the state described in the step text, not after the conditional action.