@codyswann/lisa 2.121.1 → 2.122.0

package/plugins/lisa-rails-agy/skills/exploratory-qa/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: exploratory-qa
+description: First-time-user exploratory QA walkthrough for web apps that FEEDS THE LIFECYCLE. Use when asked to experience an app the way a brand-new human user would — landing cold on the home page and clicking through to find anything confusing, broken, or hard to understand (machine-style labels, slow or unclear loads, cramped or cut-off UI, inconsistent/non-standard UX, awkward scroll behavior, unclear affordances) across all breakpoints. Instead of writing a report file, it files every finding as a tracked work item via lisa:tracker-write (bugs and usability/UX issues). A `ready` parameter controls whether those tickets are created build-ready (auto-picked-up by lisa:intake) or left in the backlog for human triage (default). For gaps in the automated Playwright test suite, use the e2e-coverage-gaps skill instead.
+---
+
+# Exploratory QA
+
+## Overview
+
+Experience the app the way a **brand-new human user** would: land cold on the home page with no prior
+knowledge, then click through and actually try to use it — just like a real person. The goal is to
+surface anything **confusing, broken, or hard to understand**, and to do so at **every breakpoint**.
+
+This is a usability/experience pass, **not** a test-coverage audit. It does not look at the Playwright
+suite or hunt for coverage gaps — for that, use the `e2e-coverage-gaps` skill. Here, every finding is
+filed as a tracked work item so it enters the Lisa lifecycle — no static report file.
+
+## Parameters
+
+- **`target-url | env`** (first positional) — what to explore.
+- **`ready=true|false`** — the build-ready state for the tickets this pass creates.
+  - `ready=true` → created build-ready, so `lisa:intake` / the build-intake scanner auto-picks them up.
+  - `ready=false` (**default**) → created in the backlog (not build-ready) for a human to review and
+    promote into the queue.
+
+## Core Workflow
+
+### 1. Establish Scope
+
+- Identify the target environment, account type, and browser requirement, and read the `ready` flag
+  (default `false`).
+- **Confirm the tracker is configured.** Findings are filed as tickets, so read `tracker` from
+  `.lisa.config.json` (local overrides global). If it is unset, stop and report that the tracker must
+  be configured (via `/lisa:setup:jira` / `:github` / `:linear`) before exploratory QA can file
+  findings — do not silently fall back to a report file.
+- If credentials, tenant, or seed data are missing and cannot be discovered safely, ask one concise
+  clarifying question.
+- Treat production-like environments conservatively. Do not mutate production data unless the user
+  explicitly approves it. Prefer a test user, dev/staging environment, or isolated seeded account.
+
+### 2. Arrive Cold
+
+- Start at the home/landing page with **no prior knowledge of the app**. Do **not** pre-read the
+  codebase to learn the intended flows — discover them the way a user would, by looking and clicking.
+- Form a first impression: is it obvious what this app is, what to do first, and where to go next?
+
+### 3. Use It Like a Human
+
+Click through the visible paths and actually attempt real tasks — a first-time user explores, makes
+mistakes, and tries the obvious thing. Cover at least these dimensions unless the user narrows scope:
+
+- **Comprehension & labeling:** machine-style or developer labels shown to users (raw IDs, enum keys,
+  `snake_case`, `null`/`undefined`, untranslated i18n keys), jargon, unclear button/menu names, icons
+  with no discernible meaning.
+- **Navigation clarity:** is it obvious how to get somewhere and back? Dead ends, hidden entry points,
+  surprising redirects, broken links, no clear "home".
+- **Visual/layout quality:** cut-off or truncated text, overlap, cramped/crowded density, offscreen or
+  unreachable controls, accidental horizontal scroll, awkward empty space.
+- **Consistency / standard UX:** components, spacing, button styles, terminology, and interaction
+  patterns should be consistent across the app and follow common conventions. Flag anything
+  non-standard or that differs screen-to-screen.
+- **Load & responsiveness:** long or unclear load times, blank screens, spinners / `Loading...` /
+  `Connecting...` with no progress, anything that feels slow or janky.
+- **Scroll behavior:** unexpected scroll position, scroll jumps, nested or locked scroll, sticky
+  elements that cover content, content that cannot be reached.
+- **Behavior correctness:** does the obvious action do what a user expects? Confusing errors, silent
+  failures, disabled controls with no explanation, state that does not persist.
+- **Affordance clarity:** can the user tell what is clickable, required, in-progress, or complete?
+
+### 4. Cover All Breakpoints
+
+- Discover breakpoints from the app (design tokens, CSS, responsive layout changes) when possible; if
+  unknown, use a practical baseline: phone, tablet/narrow, desktop, plus any app-specific cutoff.
+- At each breakpoint, walk the key paths again and confirm the experience holds: expected
+  shell/navigation variant, critical controls visible and reachable, no unintended horizontal
+  overflow, intentional scroll containers still usable, nothing cut off or crowded.
+
+### 5. Watch Load & Latency
+
+- Notice time to first meaningful content and time spent in blank/loading/spinner/connecting states.
+- A page can be technically interactive but still visually incomplete — note that.
+- Treat long waits without clear progress, error, retry, or cancellation as findings. Use practical
+  labels (noticeable, slow, unacceptable) and include observed durations when available.
+
+## Mutation Discipline
+
+A real first-time user creates, edits, and deletes things — exercise those flows when the environment
+is safe.
+
+- Use unique names with a clear prefix such as `qa-` or `codex-`.
+- Before mutating, identify the cleanup path. After mutating, make a best effort to clean up through
+  the UI, then verify cleanup. If UI cleanup is unavailable, that itself is a usability finding.
+- Avoid destructive bulk actions unless the user explicitly asks or the account is clearly disposable.
+- Record all mutations performed, cleanup attempts, and any residue left behind.
+
+## Filing findings as tracked work
+
+This skill does **not** write a report file. Every finding becomes a **leaf work item** created via
+`lisa:tracker-write` (the vendor-neutral writer — it dispatches to the configured tracker and runs the
+validation gate; never call a vendor `*-write-*` skill directly). Map each finding to a type:
+
+| Finding | `issue_type` | `build_ready` |
+|---------|--------------|---------------|
+| User-visible **bug** (broken behavior) | `Bug` | the `ready` flag (default `false`) |
+| **Usability / UX / clarity issue** | `Improvement` | the `ready` flag (default `false`) |
+
+Each finding is a flat leaf (no children), so `build_ready` applies directly — pass it explicitly on
+every create. Each ticket MUST be a complete spec (the validator rejects thin tickets):
+
+- **Three-audience description** (context / business value, technical approach, stakeholder impact).
+- **For a bug:** exact reproduction steps, observed-vs-expected, the env / account / breakpoint it
+  occurred at, and console/network evidence.
+- **For a usability issue:** the observed friction (what was confusing, cramped, inconsistent, or hard
+  to understand), who it affects, **where** (route + breakpoint), and the proposed improvement.
+- **Gherkin acceptance criteria** describing the fixed behavior.
+
+### Idempotency — don't spam duplicates
+
+Re-running a pass must not refile the same finding. Before creating a ticket, search the tracker for an
+**open** ticket carrying a stable marker `[lisa-exploratory-qa] <finding-key>` in its body (the
+`<finding-key>` is a stable slug of surface + symptom, e.g. `settings-modal/horizontal-overflow@tablet`).
+If one exists, reference/update it instead of creating a duplicate; only create when none exists.
+**Match by the marker, never by title** (titles get edited). A *closed* prior ticket does not suppress a
+new one — a recurrence after a fix is a genuine regression.
+
+## Output
+
+No report file. Emit a concise in-session summary:
+
+- **Scope:** target URL/env, browser/tool, account type, build/version if visible, date.
+- **First impression:** could a new user tell what the app is and what to do first?
+- **Findings filed**, bucketed by type — bugs, usability/clarity issues — each with its **created or
+  referenced ticket ref** and its **build-ready state** (`ready` vs `triage/backlog`).
+- **Observed but not filed:** anything noticed but intentionally not ticketed, with why.
+
+## Quality Bar
+
+- Explore as a true first-time user — judge clarity, not whether you (who can read the code) can figure
+  it out.
+- Prefer concrete, reproducible findings. Every ticket must stand alone for an implementer who was not
+  in the session.
+- Do not claim cleanup succeeded unless verified.
+- File tickets per the `ready` flag (default: backlog for human triage).
+- This skill is about the human experience only — route automated-coverage gaps to `e2e-coverage-gaps`.
+- Preserve unrelated repo changes.

package/plugins/lisa-rails-agy/skills/fix-linter-error/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fix-linter-error
+description: This skill should be used when fixing all violations of one or more RuboCop cops across the codebase. It runs RuboCop, groups violations by cop and file, generates a brief with fix strategies, and creates a plan with tasks to implement the fixes.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Fix Linter Errors
+
+Target cops: $ARGUMENTS
+
+If no arguments provided, prompt the user for at least one RuboCop cop name.
+
+## Step 1: Gather Requirements
+
+1. **Parse cops** from $ARGUMENTS (space-separated)
+2. **Run RuboCop** to collect all violations:
+   ```bash
+   bundle exec rubocop --format json 2>&1
+   ```
+3. **Group violations** by cop, then by file, noting:
+   - File path and line numbers
+   - Violation count per file
+   - Sample offense messages
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Fix RuboCop violations for cops: $ARGUMENTS
+
+Violations by cop:
+- [CopName1]: X total violations across Y files
+  - [file]: N violations (lines: ...)
+  - ...
+- [CopName2]: X total violations across Y files
+  - ...
+
+Fix strategies: extract methods, reduce complexity, apply auto-correct where safe
+
+Verification: `bundle exec rubocop --format simple 2>&1 | grep -E "($ARGUMENTS)" | wc -l` -> Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-rails-agy/skills/improve-code-complexity/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: improve-code-complexity
+description: This skill should be used when reducing the code complexity threshold of the codebase. It lowers the CyclomaticComplexity threshold by 2, identifies methods that exceed the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to fix all violations.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# Lower Code Complexity
+
+Reduces the CyclomaticComplexity threshold by 2 and fixes all violations.
+
+## Step 1: Gather Requirements
+
+1. **Read current threshold** from `.rubocop.yml` (`Metrics/CyclomaticComplexity` Max)
+2. **Calculate new threshold**: current - 2 (e.g., 10 -> 8)
+3. **Run RuboCop and flog** to find violations:
+   ```bash
+   bundle exec rubocop --only Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity --format json 2>&1
+   ```
+   ```bash
+   bundle exec flog --all --group app/ 2>&1 | head -50
+   ```
+4. **Note for each violation**:
+   - File path and line number
+   - Method name
+   - Current complexity score (RuboCop and/or flog)
+
+If no violations at new threshold, report success and exit.
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Reduce CyclomaticComplexity threshold from [current] to [new].
+
+Methods exceeding threshold (ordered by complexity):
+1. [file:method_name] (complexity: X, target: [new]) - Line Y
+   - flog score: Z
+2. ...
+
+Configuration change: .rubocop.local.yml, Metrics/CyclomaticComplexity Max from [current] to [new]
+
+Refactoring strategies: extract methods, early returns, extract conditions, use lookup hashes, replace conditionals with polymorphism
+
+Verification: `bundle exec rubocop --only Metrics/CyclomaticComplexity --format simple 2>&1 | grep "offense" | wc -l` -> Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-rails-agy/skills/improve-max-lines/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: improve-max-lines
+description: This skill should be used when reducing the maximum class/module lines threshold and fixing all violations. It updates the RuboCop configuration, identifies classes and modules exceeding the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to split oversized files.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Reduce Max Lines
+
+Target threshold: $ARGUMENTS lines per class/module
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Read current config** from `.rubocop.yml` or `.rubocop.local.yml` (`Metrics/ClassLength` and `Metrics/ModuleLength`)
+2. **Run RuboCop** with the target threshold to find violations:
+   ```bash
+   bundle exec rubocop --only Metrics/ClassLength,Metrics/ModuleLength --format json 2>&1
+   ```
+3. **Note for each violation**:
+   - File path
+   - Class/module name
+   - Current line count
+
+If no violations at $ARGUMENTS, report success and exit.
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Reduce max class/module lines threshold to $ARGUMENTS.
+
+Classes/modules exceeding threshold (ordered by line count):
+1. [file:ClassName] - [current] lines (target: $ARGUMENTS)
+2. ...
+
+Configuration change: .rubocop.local.yml, Metrics/ClassLength Max to $ARGUMENTS, Metrics/ModuleLength Max to $ARGUMENTS
+
+Refactoring strategies: extract concerns, extract service objects, remove duplication, delete dead code, simplify logic
+
+Verification: `bundle exec rubocop --only Metrics/ClassLength,Metrics/ModuleLength --format simple 2>&1 | grep "offense" | wc -l` -> Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-rails-agy/skills/improve-max-lines-per-function/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: improve-max-lines-per-function
+description: This skill should be used when reducing the maximum lines per method threshold and fixing all violations. It updates the RuboCop configuration, identifies methods exceeding the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to split oversized methods.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Reduce Max Lines Per Method
+
+Target threshold: $ARGUMENTS lines per method
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Read current config** from `.rubocop.yml` or `.rubocop.local.yml` (`Metrics/MethodLength`)
+2. **Run RuboCop** with the target threshold to find violations:
+   ```bash
+   bundle exec rubocop --only Metrics/MethodLength --format json 2>&1
+   ```
+3. **Note for each violation**:
+   - File path and line number
+   - Method name
+   - Current line count
+
+If no violations at $ARGUMENTS, report success and exit.
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Reduce max lines per method threshold to $ARGUMENTS.
+
+Methods exceeding threshold (ordered by line count):
+1. [file:method_name] (lines: X, target: $ARGUMENTS) - Line Y
+2. ...
+
+Configuration change: .rubocop.local.yml, Metrics/MethodLength Max to $ARGUMENTS
+
+Refactoring strategies: extract methods, early returns, extract conditions, use lookup hashes, consolidate logic
+
+Verification: `bundle exec rubocop --only Metrics/MethodLength --format simple 2>&1 | grep "offense" | wc -l` -> Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-rails-agy/skills/improve-test-coverage/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: improve-test-coverage
+description: This skill should be used when increasing test coverage to a specified threshold percentage. It runs the test suite with SimpleCov, identifies files with the lowest coverage, generates a brief with coverage gaps, and creates a plan with tasks to add the missing tests.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Increase Test Coverage
+
+Target threshold: $ARGUMENTS%
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Find coverage config** (`.simplecov` or `spec/spec_helper.rb`)
+2. **Run test suite with coverage** to get current state:
+   ```bash
+   bundle exec rspec 2>&1 | tail -50
+   ```
+3. **Check SimpleCov output** in `coverage/index.html` or console output
+4. **Identify the 20 files with lowest coverage**, noting:
+   - File path
+   - Current coverage % (lines, branches)
+   - Which lines/branches are uncovered
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Increase test coverage from [current]% to $ARGUMENTS%.
+
+Files needing coverage (ordered by coverage gap):
+1. [file] - [current]% coverage (target: $ARGUMENTS%)
+   - Uncovered: [lines]
+   - Missing branch coverage: [lines]
+2. ...
+
+Configuration: .simplecov, update minimum_coverage to $ARGUMENTS%
+
+Verification: `bundle exec rspec` -> Expected: SimpleCov reports >= $ARGUMENTS% coverage
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-rails-agy/skills/jira-add-journey/SKILL.md

@@ -0,0 +1,65 @@
+---
+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 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 verification approach, 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, description, acceptance criteria, components, labels, linked tickets.
+
+### 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, determine the appropriate verification approach. Stack-specific overrides provide the analysis logic.
+
+### Step 4: Draft the Validation Journey
+
+Compose the journey following the Validation Journey format with: Prerequisites, Steps (with evidence markers), and Assertions.
+
+### 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.
+
+### Step 6: Append to Ticket Description
+
+After user approval, use the JIRA REST API to append the Validation Journey to the existing ticket description.
+
+### 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>
+```

package/plugins/lisa-rails-agy/skills/jira-create/SKILL.md

@@ -0,0 +1,100 @@
+---
+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", "Skill", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Create JIRA Issues from $ARGUMENTS
+
+Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans structure only — every individual ticket write is delegated to `lisa:jira-write-ticket`.** Do not call `mcp__atlassian__createJiraIssue` from this skill; the necessary write tools are intentionally not in `allowed-tools`.
+
+## Process
+
+1. **Analyze**: Read $ARGUMENTS to understand scope.
+2. **Extract source artifacts**: invoke the `lisa:tracker-source-artifacts` skill, then enumerate every external URL, embed, attachment, or example payload and classify each by domain per its rules. Build the `artifacts` map. See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill to capture current behavior, design-vs-product divergence, and reuse candidates. Skip only when the work is purely backend or affects a screen that does not yet exist. See "Live Product Walkthrough" below.
+4. **Determine structure**:
+   - Epic needed if: multiple features, major changes, >3 related files
+   - Direct tasks if: bug fix, single file, minor change
+5. **Plan hierarchy**:
+   ```text
+   Epic → User Story → Tasks (test, implement, document, cleanup)
+   ```
+6. **Delegate every write to `lisa:jira-write-ticket`** in dependency order (epic first, then stories with the epic as parent, then sub-tasks with their story as parent). Pass the artifacts (filtered by domain per `lisa:tracker-source-artifacts` inheritance rules) and the walkthrough findings (under `## Current Product`). See "Delegation to jira-write-ticket" below.
+7. **Run the artifact preservation gate** (`lisa:tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created tickets. Fail loudly if anything was dropped.
+
+## 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
+
+## Source Artifacts
+
+If $ARGUMENTS includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as remote links on the created tickets. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke the `lisa:tracker-source-artifacts` skill** for the canonical rules: domains, per-tool classification (Figma `/proto/` vs design, Lovable, Loom, screenshots), source precedence, conflict handling under `## Open Questions`, inheritance from epic → story → sub-task, and the existing-component reuse expectation. Do not restate the rules here.
+
+Rails-specific note: the existing-component reuse rule applies to view partials and ViewComponents — the closest existing partial/component is usually the right answer over pixel-matching a mock from scratch.
+
+When delegating writes to `lisa:jira-write-ticket`, pass the extracted artifact list so its Phase 4c step can attach them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill before drafting tickets. Findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the ticket plan and surface under `## Current Product` on the resulting tickets. Skip only when the work is purely backend or affects a screen that does not yet exist.
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default project: SE (override via arguments)
+Exclude unless requested: migration plans, performance tests
+
+## Delegation to jira-write-ticket
+
+**Mandatory.** Every ticket created by this skill MUST go through `lisa:jira-write-ticket`. This skill never calls `mcp__atlassian__createJiraIssue` itself — that tool is intentionally excluded from `allowed-tools` so the gate cannot be bypassed.
+
+`lisa:jira-write-ticket` enforces things this skill does not, and which determine ticket quality:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation (non-bug, non-epic types)
+- Explicit link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Remote links (PRs, Confluence, dashboards)
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+### Invocation order
+
+Tickets must be created in parent-before-child order so each child can be passed its parent key:
+
+1. Invoke `lisa:jira-write-ticket` for the epic. Capture the returned key.
+2. For each story, invoke `lisa:jira-write-ticket` with the epic key as the epic parent. Capture each story key.
+3. For each sub-task, invoke `lisa:jira-write-ticket` with the parent story key.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, project key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent key (epic key for stories; story key for sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules — `lisa:jira-write-ticket` Phase 4c attaches them as remote links
+- For tickets that change runtime behavior: the Validation Journey draft, or instruct it to call `lisa:jira-add-journey` after create
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's an epic vs. story vs. sub-task)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent keys through subsequent writes
+- Running the artifact preservation check after all writes complete
+
+It does not own the actual JIRA write — that's `lisa:jira-write-ticket`'s job.

package/plugins/lisa-rails-agy/skills/jira-evidence/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: jira-evidence
+description: "Upload evidence to GitHub pr-assets release, update PR description, upload attachments to JIRA, post comment, and move ticket to Code Review. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/comment.md."
+---
+
+# JIRA Evidence Posting
+
+Upload captured evidence and generated templates to GitHub PR description and JIRA ticket. This skill is the posting step — it assumes evidence files 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 evidence 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:
+  - Evidence files: `NN-name-viewport.png` (screenshots) and/or `NN-name.txt`/`NN-name.json` (text evidence)
+  - `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 evidence files via `gh release upload --clobber`, creating CDN URLs
+3. **Update PR description** — Replaces or appends the `## Evidence` section in the PR body using `gh pr edit`
+4. **Upload JIRA attachments** — Uploads image evidence 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)
+6. **Move ticket to Code Review** — Transitions the JIRA ticket via `jira issue move`
+
+## Evidence Naming Conventions
+
+- Image evidence: `NN-name-viewport.png` (e.g., `01-search-step-desktop.png`)
+- Text evidence: `NN-name.txt` or `NN-name.json` (e.g., `01-health-check.json`)
+
+## Troubleshooting
+
+### Images not rendering in GitHub PR
+
+Images must be in the `pr-assets` GitHub release. If the release does not exist, create it first:
+
+```bash
+gh release create pr-assets --title "PR Assets" --notes "CDN for PR evidence"
+```
+
+### 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.
+
+### 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.