@codyswann/lisa 2.119.0 → 2.121.0

package/plugins/lisa-agy/skills/jira-sync/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: jira-sync
+description: "Syncs plan progress to a linked JIRA ticket. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep tickets in sync."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# JIRA Ticket Sync
+
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Sync current plan progress to JIRA ticket: $ARGUMENTS
+
+If no argument provided, search for a ticket URL in the active plan file (most recently modified `.md` in `plans/`).
+
+## Workflow
+
+### Step 1: Identify Ticket and Context
+
+1. **Parse ticket ID** from `$ARGUMENTS` or extract from the active plan file
+2. **Fetch current ticket state** by invoking `lisa:atlassian-access` via the Skill tool with `operation: read-ticket key: <TICKET-ID>`
+3. **Determine current milestone** by checking:
+   - Does a plan file exist? → Plan created
+   - Is there a working branch? → Implementation started
+   - Are tasks in progress? → Active implementation
+   - Is there an open PR? → PR ready for review
+   - Is the PR merged? → Complete
+
+### Step 2: Gather Update Content
+
+Based on the current milestone:
+
+| Milestone | Content to Post |
+|-----------|-----------------|
+| **Plan created** | Plan summary, branch name, link to PR (if draft exists) |
+| **Implementation in progress** | Task completion summary (X of Y tasks done), any blockers |
+| **PR ready** | PR link, summary of changes, test results |
+| **PR merged** | Final summary, suggest moving ticket to "Done" |
+
+### Step 3: Post Update
+
+Before adding a comment, check for an existing milestone comment to avoid duplicates (idempotency):
+
+1. **Fetch existing comments** by invoking `lisa:atlassian-access` with `operation: search-issues jql: "..."` or by reading the ticket's comments. Look for a comment whose body contains a stable milestone marker (e.g., the heading `## Plan Created`, `## Implementation in Progress`, `## PR Ready`, or `## PR Merged`) that matches the current milestone.
+2. **If a matching comment already exists**, skip posting and proceed to field updates — idempotent re-runs must not create duplicates.
+3. **If no matching comment exists**, add a new comment by invoking `lisa:atlassian-access` with `operation: comment key: <TICKET-ID> body: "..."`.
+4. **Update ticket fields** if applicable:
+   - Add branch name to a custom field or comment
+   - Add PR link to a custom field or comment
+5. **Report** what was synced to the user
+
+### Step 4: Suggest Status Transition
+
+Based on the milestone, suggest (but don't automatically perform) a status transition:
+
+| Milestone | Suggested Status |
+|-----------|-----------------|
+| Plan created | "In Progress" |
+| PR ready | "In Review" |
+| PR merged | "Done" |
+
+### Step 5: Parent Status Rollup (`--rollup`)
+
+When invoked with `--rollup`, this skill **derives a parent/container ticket's status from the roll-up of its children** (Stories under an Epic; Sub-tasks under a Story/Task) instead of posting a milestone update on a leaf. This implements the JIRA child/subtask-status arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy.
+
+**Resolve the child set the same way `lisa:jira-read-ticket` does** — the native Epic → Story → Sub-task hierarchy (Epic link / parent field for Stories, the subtask relationship for Sub-tasks), each with its current status. Fetch via `lisa:atlassian-access` (`operation: read-ticket` / `search-issues` with the parent's `"Epic Link" = <KEY>` or `parent = <KEY>` JQL). If the ticket has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
+
+**Evaluate the required children in priority order and take the first match** (canonical roles from `config-resolution`; the JIRA status map defaults to `Blocked`, `In Progress`, `Code Review`, env-keyed `done`):
+
+| If among the required child leaves… | Derived parent role | JIRA status |
+|---|---|---|
+| any child is **blocked** | `blocked` | `Blocked` |
+| else any child is **in progress** (`In Progress` or `Code Review`) | `claimed` | `In Progress` |
+| else **all** required children are terminal (`Done`) | `done` | the configured terminal `done` status |
+| else (children exist, none started) | — | unchanged — parent keeps its non-ready container status |
+
+- **Blocked dominates** — a single blocked child surfaces `Blocked` on the parent even while siblings progress.
+- **"Required" children only** — won't-do / optional children do not hold the parent open.
+- **Recursive** — an Epic reaches `Done` only when its Stories have themselves rolled up to `Done`; a Story reaches `Done` only when its Sub-tasks are all terminal. Evaluate bottom-up.
+- **Never set the parent to the build-ready status** — `ready` is leaf-only. Rollup only moves the parent between non-ready container statuses.
+- **`review` is optional for JIRA** (`config-resolution`) — a project that omits `Code Review` keeps the parent in `In Progress` until terminal; skip the intermediate rollup hop rather than forcing a non-existent status (a `leaf-only-lifecycle` "vendor support varies" note).
+
+**Single-environment collapse (this repo).** The terminal `done` resolves via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to a single status and the lifecycle is `Ready → In Progress → Code Review → Done` with **no** dev/staging promotion hops; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map.
+
+**Apply the derived status** (only when it differs from the parent's current status) via `lisa:atlassian-access` `operation: transition`, and post an idempotent rollup comment naming the derived state and the child tally. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's status untouched.
+
+## Important Notes
+
+- **Never auto-transition ticket status** — always suggest and let the user confirm. The one exception is the explicit `--rollup` parent derivation (Step 5), which transitions a *parent's* status per the `leaf-only-lifecycle` rule — never a leaf's, and never to the build-ready status.
+- **Idempotent updates** — running sync multiple times at the same milestone should not create duplicate comments
+- **Comment format** — use JIRA markdown with clear headers and bullet points
+- **Rollup cites the rule by slug** — parent state derivation follows the `leaf-only-lifecycle` rule's state machine; this skill does not restate the policy.
+
+## Execution
+
+Sync the ticket now.

package/plugins/lisa-agy/skills/jira-validate-ticket/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: jira-validate-ticket
+description: "Validates a proposed JIRA ticket spec (or an existing ticket) against the organizational quality gates without writing anything. Returns a structured PASS/FAIL report per gate with concrete remediation. This is the single source of truth for what makes a valid ticket — both the write path (jira-write-ticket runs it pre-write) and the dry-run path (notion-to-tracker runs it during PRD intake) call this skill so the bar can never drift."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Validate JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Run all organizational quality gates against a ticket spec OR an existing ticket. **This skill is read-only — it never writes to JIRA.** The output is a structured report consumed by callers (`lisa:jira-write-ticket` for pre-write gating, `lisa:notion-to-tracker` for PRD dry-run, `lisa:jira-verify` for post-write checks).
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+1. **An existing ticket key** (e.g. `PROJ-1234`): fetch it and validate the live state. Use this for post-write checks.
+2. **A proposed ticket spec** (YAML block, see schema below): validate as-is without touching JIRA. Use this for pre-write and dry-run checks.
+
+### Spec schema
+
+Specs are passed as a fenced YAML block. Required keys depend on `issue_type`.
+
+```yaml
+issue_type: Story          # Story | Task | Bug | Epic | Spike | Sub-task | Improvement
+project_key: SE
+summary: "[CU-1.2] Upload contract PDF from settings"
+priority: Medium
+parent_key: SE-1234        # Epic key for non-Bug/non-Epic; Story key for Sub-task
+description: |             # Full description text — every required section
+  h2. Context / Business Value
+  ...
+
+  h2. Technical Approach
+  ...
+
+  h2. Acceptance Criteria
+  # Given <precondition>
+    When <action>
+    Then <observable outcome>
+
+  h2. Out of Scope
+  ...
+
+  h2. Target Backend Environment
+  dev
+
+  h2. Sign-in Required
+  Account: ...
+
+  h2. Repository
+  backend-api
+
+  h2. Validation Journey
+  ...
+
+# Behavioral flags — caller asserts these so the validator can pick the right gates
+runtime_behavior_change: true     # → requires Target Backend Environment + Validation Journey
+authenticated_surface: true       # → requires Sign-in Required
+artifacts_attached: true          # → requires Source Precedence section
+links: [{ key: "PROJ-99", type: "is blocked by" }]   # known issue links (may be empty)
+remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
+build_ready: true                 # caller asserts the build-ready role (status:ready) is/would be applied — see S15
+child_refs: ["PROJ-601", "PROJ-602"]   # known child work (sub-tasks / "is blocked by" parentage) — see S15
+```
+
+If the caller passes only a ticket key, fetch the ticket via `lisa:atlassian-access` `operation: read-ticket key: <KEY>`, derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa:jira-read-ticket`) so S15 can classify the ticket — then run gates.
+
+## Gates
+
+Gates are grouped into **Specification** (spec-only checks, no JIRA lookups) and **Feasibility** (requires JIRA lookups). The dry-run path may opt to run Specification gates only; the write path runs both.
+
+Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Categories drive how downstream callers (notably `lisa:notion-prd-intake`) translate failures into product-facing comments; `product_relevant=false` failures indicate internal data-quality problems (broken parent links, missing core fields) that the agent should fix itself rather than ask product to clarify.
+
+| Gate | Category | Product-relevant |
+|------|----------|------------------|
+| S1 Required core fields | `structural` | false |
+| S2 Summary format | `structural` | false |
+| S3 Description three audiences | `product-clarity` | true |
+| S4 Acceptance criteria in Gherkin | `acceptance-criteria` | true |
+| S5 Bug-specific content | `product-clarity` | true |
+| S6 Spike-specific content | `scope` | true |
+| S7 Epic parent declared | `structural` | false |
+| S8 Target Backend Environment | `technical` | false |
+| S9 Sign-in Required | `technical` | false |
+| S10 Single-repo scope | `scope` | false |
+| S11 Validation Journey | `acceptance-criteria` | true |
+| S12 Source Precedence | `design-ux` | true |
+| S13 Relationship Search | `dependency` | true |
+| S14 Evidence manifest binding (leaf work units) | `acceptance-criteria` | true |
+| S15 Leaf-only build-ready | `structural` | false |
+| F1 Issue type valid in project | `structural` | false |
+| F2 Epic parent exists and is an Epic | `structural` | false |
+| F3 Linked tickets exist | `structural` | false |
+| F4 Required custom fields populated | `structural` | false |
+
+Category values are drawn from this fixed set:
+
+- `product-clarity` — feature behavior or user intent unclear in the PRD
+- `acceptance-criteria` — pass/fail conditions missing or ambiguous
+- `design-ux` — visual or interaction spec missing
+- `scope` — boundary unclear, items overlap, split needed
+- `dependency` — blocked by another team / system / decision
+- `data` — data source / shape / volume unspecified
+- `technical` — engineering decision required (rare from PRD path; mostly internal)
+- `structural` — internal data-quality problem the agent must fix itself, not surface to product
+
+### Specification Gates
+
+#### S1 — Required core fields
+
+`project_key`, `issue_type`, `summary`, `priority`, `description` must all be present and non-empty.
+
+#### S2 — Summary format
+
+- Single line, ≤ 100 characters
+- Imperative voice ("Add X", "Fix Y", not "Adding X" or "X is broken")
+- Bug / Task / Sub-task summaries SHOULD start with a `[repo-name]` prefix when the project convention uses one
+
+#### S3 — Description has all three audiences
+
+Description text must include all of these sections (case-insensitive `h2.` headings):
+- `Context / Business Value` — stakeholder-facing
+- `Technical Approach` — developer-facing
+- `Acceptance Criteria` — coding-assistant-facing
+- `Out of Scope` — explicit non-coverage list
+
+Missing any → FAIL with name of missing section.
+
+#### S4 — Acceptance criteria in Gherkin
+
+Applies when `issue_type ∈ {Story, Task, Bug, Sub-task, Improvement}`.
+
+The `Acceptance Criteria` section must contain at least one criterion in `Given / When / Then` form. Reject prose-only criteria, "should work" language, or numbered lists without Given/When/Then verbs.
+
+#### S5 — Bug-specific content
+
+When `issue_type = Bug`, description must additionally include:
+- Reproduction steps
+- Expected vs. actual behavior
+- Environment where reproduced
+
+#### S6 — Spike-specific content
+
+When `issue_type = Spike`, description must include:
+- The question being answered
+- Definition of done (decision doc / prototype / findings deliverable)
+
+#### S7 — Epic parent declared
+
+When `issue_type ∉ {Bug, Epic}`, `parent_key` must be set. (Validity of the key is checked in feasibility gates.)
+
+#### S8 — Target Backend Environment
+
+When `runtime_behavior_change = true`, description must contain `h2. Target Backend Environment` with one of `dev`, `staging`, `prod`. Skipped for doc-only / config-only / type-only / Epic.
+
+#### S9 — Sign-in Required
+
+When `authenticated_surface = true`, description must contain `h2. Sign-in Required` naming the account/role and credential source (1Password item, env var, seeded fixture).
+
+If the spec doesn't set `authenticated_surface`, infer it: scan the description and AC for sign-in / login / "as a {role} user" / authenticated route signals. If signals present and no `Sign-in Required` section: FAIL.
+
+#### S10 — Repository section, single-repo scope
+
+When `issue_type ∈ {Bug, Task, Sub-task, Improvement}`, description must contain `h2. Repository` naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation `"Split into per-repo work units under a shared parent Story (see lisa:task-decomposition step 1.5)"`.
+
+Story / Epic / Spike: skipped (may span repos — these are coordination containers, not work units).
+
+This gate is `product_relevant: false` because cross-repo work units are not a product question — they are a decomposition error. Callers (`lisa:notion-to-tracker`, `lisa:confluence-to-tracker`, `lisa:linear-to-tracker`, `lisa:github-to-tracker`) MUST pre-split cross-repo work into per-repo work units during the decomposition phase per `lisa:task-decomposition` step 1.5; an S10 failure here indicates the agent skipped that step and must auto-split + revalidate before writing, not surface a clarifying comment to product.
+
+#### S11 — Validation Journey present
+
+When `runtime_behavior_change = true`, description must contain `h2. Validation Journey`. Skipped for doc-only / config-only / type-only / Epic.
+
+The caller controls the strictness by passing `journey_followup: "auto"` or `journey_followup: "none"` in the spec:
+- `auto` (default): if the section is absent, return `FAIL` with remediation `"Invoke lisa:jira-add-journey to append the section after create"`. Callers like `lisa:jira-write-ticket` know to chain `lisa:jira-add-journey` automatically, so this counts as a fixable failure they can resolve in-line — they re-run validation after appending.
+- `none`: missing section is a `FAIL` that the caller will not auto-fix, so the verdict gates progress (used by dry-run paths like `lisa:notion-to-tracker` PRD intake, where there's no agent standing by to add the journey).
+
+Either way the gate emits `FAIL`, not a third state. Strictness is the caller's policy, not the validator's.
+
+#### S12 — Source Precedence (when artifacts attached)
+
+When `artifacts_attached = true`, description must include source-precedence guidance covering: business rules → PRD body, visual treatment → mocks, flow → prototypes, API/data → data artifacts. Cross-axis conflicts surfaced under `## Open Questions`.
+
+Accept either placement — both are valid per `lisa:tracker-source-artifacts`:
+- A dedicated `## Source Precedence` (or `h2. Source Precedence`) subsection, OR
+- A "Source Precedence" / "source precedence" / "authoritative source" paragraph under `Technical Approach` that covers the four axes above.
+
+Detect by scanning for the phrase `Source Precedence` (case-insensitive) anywhere in the description, AND verifying the four axes (business rules, visual, flow, data) are each named. Missing the phrase OR missing one or more axes: FAIL with a remediation that names the missing axes.
+
+#### S13 — Relationship Search documented
+
+The ticket must EITHER have at least one issue link in `links`, OR the description / a comment must contain a `## Relationship Search` block listing the git history queries and JQL queries that were run with their outcomes ("Searched git history for `<keywords>` and JQL for component=`X`; no related work found.").
+
+A ticket with zero links and no documented search: FAIL.
+
+#### S14 — Evidence manifest binding (leaf work units)
+
+When `issue_type ∈ {Bug, Task, Sub-task, Improvement}` AND `runtime_behavior_change = true`, the `h2. Validation Journey` must declare at least one `[EVIDENCE: name]` marker. Each marker name must be kebab-case and unique within the ticket. These markers are the work unit's **evidence manifest** — the exact, enumerated set of artifacts that must be captured and attached before the ticket may be marked complete (see the "Per-Work-Unit Evidence Contract" section of the `verification` rule, the Definition of Done in `verification-lifecycle`, and the evidence-manifest gate in `tracker-evidence`).
+
+FAIL when the Validation Journey is present but declares zero `[EVIDENCE: name]` markers, or when any marker name is empty, duplicated, or not kebab-case. A behavior-changing work unit SHOULD declare both a success marker and an error/edge marker; a journey with only one marker passes but the remediation should recommend adding the error/edge case.
+
+This gate depends on S11. It is `N/A` for Epic / Story / Spike (coordination containers, not work units) and for leaf units with `runtime_behavior_change = false` (doc-only / config-only / type-only). If S11 fails because the Validation Journey is absent, S14 also FAILs (there is no manifest to bind) with remediation pointing back to `lisa:jira-add-journey`.
+
+#### S15 — Leaf-only build-ready
+
+Enforces the build-side of the vendor-neutral `leaf-only-lifecycle` rule: **only a leaf work unit may carry the build-ready role.** This is the symmetric write-side guard for the JIRA validator — a stale or hand-applied `status:ready` label on a container is a lifecycle error and must FAIL here, regardless of how the ticket was produced. (Mirrors the "Build-ready label is leaf-only" rule that `lisa:jira-write-ticket` applies at write time.)
+
+**When the gate applies.** Run S15 whenever the ticket is build-ready — i.e. `build_ready = true`, or the spec/live labels include `status:ready`. If the ticket is not build-ready, S15 is `N/A` (nothing claims a non-ready ticket, so the invariant is vacuous).
+
+**Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an item is a **container** if it has child work, whatever its declared type; otherwise the **issue type** decides. Determine child work from (in order) `child_refs`, native sub-tasks, and `is blocked by` / parent references — the same hierarchy resolution `lisa:jira-read-ticket` uses. When validating a live key, query sub-tasks alongside the ticket fetch.
+
+Apply this decision and FAIL the two invariant-violating cases:
+
+1. **Container with child work + build-ready** — `issue_type ∈ {Epic, Story, Spike}` OR child work is present (any type that has children), AND build-ready. FAIL. A parent organizes work; it is never claimed and implemented directly. Its lifecycle state rolls up from its children.
+2. **Childless container-type + build-ready** — `issue_type ∈ {Epic, Story, Spike}` with **no** child work, AND build-ready. Still FAIL: these types are coordination containers by design, and an empty one is an incomplete decomposition, not an implementable unit (the childless-parent exception in `leaf-only-lifecycle` does **not** promote an Epic/Story/Spike to build-ready).
+
+PASS (the childless-parent exception) when the ticket is build-ready and is a **leaf work unit**: `issue_type ∈ {Bug, Task, Sub-task, Improvement}` AND has **no** child work. A flat Task or Bug with no sub-tasks is a valid build-ready leaf and must not be stranded.
+
+| issue_type | has child work | build-ready | S15 |
+|---|---|---|---|
+| Bug / Task / Sub-task / Improvement | no | yes | **PASS** (leaf) |
+| Bug / Task / Sub-task / Improvement | yes | yes | **FAIL** (structurally a container) |
+| Epic / Story / Spike | yes | yes | **FAIL** (container with children) |
+| Epic / Story / Spike | no | yes | **FAIL** (childless container-type, exception does not apply) |
+| any | any | no | **N/A** (not build-ready) |
+
+Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle. Move status:ready off this container onto its leaf children (or, for a childless Epic/Story/Spike, decompose it into leaf children or reclassify it to a leaf type); a parent's lifecycle state rolls up from its children and is never set to ready directly."`
+
+`product_relevant: false` — a build-ready container is a lifecycle/decomposition error for the caller to repair, not a product question.
+
+### Feasibility Gates (require JIRA lookups; skip in dry-run if requested)
+
+#### F1 — Issue type valid in project
+
+Invoke `lisa:atlassian-access` to fetch issue-type metadata for `project_key` and confirm `issue_type` exists.
+
+#### F2 — Epic parent exists and is an Epic
+
+When `parent_key` is set for non-Sub-task: fetch via `lisa:atlassian-access` `operation: read-ticket key: <parent_key>`, confirm the issue type is `Epic`. For Sub-task, confirm the parent is a non-Sub-task in the same project.
+
+#### F3 — Linked tickets exist
+
+For each entry in `links`, invoke `lisa:atlassian-access` `operation: read-ticket key: <link.key>` to confirm the key resolves. Flag broken keys.
+
+#### F4 — Required custom fields populated
+
+Use the same project-issue-type-metadata lookup from F1 (via `lisa:atlassian-access`) to learn required custom fields for the issue type. Any required custom field not provided in the spec: FAIL.
+
+## Execution
+
+1. Parse `$ARGUMENTS`. If it's a ticket key, fetch the ticket via `lisa:atlassian-access` `operation: read-ticket` and derive the spec from the fetched fields — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa:jira-read-ticket`) so S15 can classify the ticket. Otherwise parse the YAML spec.
+2. If any feasibility gate will run, invoke `lisa:atlassian-access` `operation: list-sites` once to confirm the configured site is reachable (it enforces connection match against `.lisa.config.json`).
+3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
+4. Unless the caller passed `--spec-only` (dry-run), run every Feasibility gate. Collect results.
+5. Emit the report below.
+
+## Output
+
+Output is a single fenced text block. Callers parse it; do not add free-form prose around it.
+
+```text
+## jira-validate-ticket: <TICKET-KEY-or-SUMMARY>
+
+### Specification Gates
+- [PASS|FAIL|N/A] S1 Required core fields — <one-line reason>
+- [PASS|FAIL|N/A] S2 Summary format — <one-line reason>
+- [PASS|FAIL|N/A] S3 Description three audiences — <one-line reason>
+- [PASS|FAIL|N/A] S4 Acceptance criteria in Gherkin — <one-line reason>
+- [PASS|FAIL|N/A] S5 Bug-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S6 Spike-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S7 Epic parent declared — <one-line reason>
+- [PASS|FAIL|N/A] S8 Target Backend Environment — <one-line reason>
+- [PASS|FAIL|N/A] S9 Sign-in Required — <one-line reason>
+- [PASS|FAIL|N/A] S10 Single-repo scope — <one-line reason>
+- [PASS|FAIL|N/A] S11 Validation Journey — <one-line reason>
+- [PASS|FAIL|N/A] S12 Source Precedence — <one-line reason>
+- [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
+- [PASS|FAIL|N/A] S14 Evidence manifest binding — <one-line reason>
+- [PASS|FAIL|N/A] S15 Leaf-only build-ready — <one-line reason>
+
+### Feasibility Gates  (omit this section when --spec-only)
+- [PASS|FAIL|N/A] F1 Issue type valid in project — <one-line reason>
+- [PASS|FAIL|N/A] F2 Epic parent exists and is an Epic — <one-line reason>
+- [PASS|FAIL|N/A] F3 Linked tickets exist — <one-line reason>
+- [PASS|FAIL|N/A] F4 Required custom fields populated — <one-line reason>
+
+### Verdict: PASS | FAIL
+### Failures: <count>
+### Failure details
+- gate: <gate-id>
+  category: <product-clarity|acceptance-criteria|design-ux|scope|dependency|data|technical|structural>
+  product_relevant: <true|false>
+  what: <plain-language description of what is missing or wrong, no gate-IDs, no JIRA terminology — written so a non-engineer product owner understands the issue>
+  recommendation: <1–3 concrete options the caller (or downstream product team) can pick from. Never "clarify this" — always a specific suggested resolution.>
+- gate: <gate-id>
+  category: ...
+  ...
+```
+
+The verdict is `PASS` if and only if every applicable gate is `PASS`. Any `FAIL` makes the verdict `FAIL`. `N/A` does not affect the verdict.
+
+### Failure-detail fields
+
+- **gate**: the gate ID (`S1`–`S15`, `F1`–`F4`).
+- **category**: the gate's fixed category from the table above. Callers use this to label or filter comments — `product-clarity`, `acceptance-criteria`, `design-ux`, `scope`, `dependency`, `data`, `technical`, or `structural`.
+- **product_relevant**: matches the gate's table entry. `false` means the failure is an internal data-quality problem (e.g., the agent built a malformed spec, an issue type is invalid in the project) and the caller should fix it without bothering the product team. `true` means the PRD needs product input to resolve.
+- **what**: plain-language description of the issue. No gate IDs, no JIRA jargon, no engineering shorthand. A product owner reading this on a Notion comment should understand what is unclear and why.
+- **recommendation**: 1–3 concrete options the reader can pick from, not a generic "please clarify." If the answer is genuinely open-ended, list the most plausible candidate resolutions you considered, even if speculative.
+
+## Rules
+
+- Never write to JIRA. This skill only invokes `lisa:atlassian-access` with read-only operations (`read-ticket`, `search-issues`, `list-sites`); it never calls write operations (`write-ticket`, `transition`, `comment`, `link`).
+- Never auto-fix the spec. This skill reports gaps; callers decide what to do (block, ask the human, regenerate the spec).
+- Never silently skip a gate. If a gate genuinely doesn't apply, return `N/A` with the reason; never omit it.
+- The `what` and `recommendation` fields must be concrete and product-readable — the dry-run path turns each failure into a Notion comment, and the audience for those comments is the product team, not engineers. Vague guidance ("clarify this", "decide how to handle X") is useless; always give 1–3 candidate resolutions.
+- Never emit a category outside the fixed set. If a new gate doesn't fit, propose adding the category to the taxonomy in this skill rather than inventing one inline.
+- `product_relevant` is determined by the gate, not by the failure context. Do not flip it per-failure.

package/plugins/lisa-agy/skills/jira-verify/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: jira-verify
+description: This skill should be used when verifying that a JIRA ticket meets organizational standards for epic relationships and description quality. It fetches the live ticket and delegates the gate checks to jira-validate-ticket so the bar matches what jira-write-ticket enforces pre-write.
+allowed-tools: ["Skill"]
+---
+
+# Verify JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Verify that the existing JIRA ticket `$ARGUMENTS` meets organizational standards. This skill is a thin post-write wrapper around `lisa:jira-validate-ticket`: it fetches the live ticket and asks `lisa:jira-validate-ticket` to run the gates against the fetched state.
+
+This indirection exists so the gate definitions live in exactly one place (`lisa:jira-validate-ticket`). When the bar changes, change it there — `lisa:jira-verify`, `lisa:jira-write-ticket` (Phase 5.5 pre-write), and `lisa:notion-to-tracker` (PRD dry-run) all pick it up.
+
+## Process
+
+1. Invoke `lisa:atlassian-access` via the Skill tool with `operation: list-sites` to confirm the configured site is reachable (the access skill enforces connection match against `.lisa.config.json`).
+2. Fetch the ticket via `lisa:atlassian-access` `operation: read-ticket key: $ARGUMENTS`. Pull issue type, summary, description, parent, links, labels, components, and any custom fields needed.
+3. Invoke `lisa:jira-validate-ticket` and pass the ticket key. The validator fetches its own copy if needed and runs every gate (Specification + Feasibility) against the live state.
+4. Surface the validator's report verbatim to the caller.
+
+## Output
+
+Pass through `lisa:jira-validate-ticket`'s structured output unchanged. Do not summarize or paraphrase — downstream callers (e.g. `lisa:jira-agent`'s pre-flight gate) parse the gate lines.
+
+## Notes
+
+- This skill is read-only. It never edits the ticket, posts comments, or changes status.
+- If a gate fails, the recommendation is part of the validator's report; surface it as-is.
+- Validation Journey checks (S11) historically required a parser script (`parse-plan.py`); the parser logic now lives inside `lisa:jira-validate-ticket` so this skill no longer shells out to it.