@codyswann/lisa 1.95.0 → 2.0.0

package/plugins/{src/base/skills/plan-improve-tests → lisa/skills/improve-tests}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-improve-tests
+name: improve-tests
 description: This skill should be used when improving test quality. It scans the test suite for weak, brittle, or poorly-written tests, generates a brief with improvement opportunities, and creates a plan with tasks to strengthen the tests.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 ---
@@ -44,4 +44,4 @@ Test files needing improvement (ordered by impact):
 Verification: `bun run test` -> Expected: All tests pass, improved assertions and coverage
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa/skills/jira-build-intake/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: jira-build-intake
+description: "Symmetric counterpart to notion-prd-intake on the JIRA side. Scans a JIRA project (or JQL filter) for tickets in Status=Ready, claims each by transitioning to In Progress, runs the implementation/build flow via jira-agent, and transitions to On Dev on completion. The Ready status is the human-flipped signal that a TODO ticket is truly ready for development — mirroring how Notion PRDs work product Draft → Ready → (us) In Review → Blocked|Ticketed."
+allowed-tools: ["Skill", "Bash", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getJiraIssue", "mcp__atlassian__getTransitionsForJiraIssue", "mcp__atlassian__transitionJiraIssue", "mcp__atlassian__addCommentToJiraIssue"]
+---
+
+# JIRA Build Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A JIRA project key (e.g. `SE`) — scans that project for `Status = Ready` tickets.
+2. A full JQL filter (e.g. `project = SE AND component = "frontend" AND Status = Ready`) — used as-is. The skill will not append a `Status = Ready` clause if the JQL already names a status, so callers can intentionally widen.
+
+Run one build-intake cycle. Each Ready ticket is claimed, built via the `jira-agent` flow, and transitioned to `On Dev` (or the equivalent next-status for that project). The cycle is the symmetric mirror of `notion-prd-intake`: humans flip `Ready`, agents pick up and progress.
+
+## Lifecycle assumed
+
+The JIRA workflow has these statuses (or equivalents — see Configuration for renaming):
+
+```text
+TODO → Ready → In Progress → On Dev → On QA → Done
+       (PM/   (us claim)    (us done; (downstream)
+        human)               PR ready)
+```
+
+This skill ONLY transitions `Ready → In Progress` on claim, and `In Progress → On Dev` on completion. It never touches `TODO`, `On QA`, `Done`, or any blocked/closed states.
+
+**Pre-flight check**: at start of each cycle, call `getTransitionsForJiraIssue` against a sample Ready ticket to confirm `In Progress` and `On Dev` are reachable transitions. If not, stop and report the workflow misconfiguration to the caller — do not invent transitions.
+
+## Phases
+
+### Phase 1 — Resolve the query
+
+1. Parse `$ARGUMENTS`:
+   - Project key: build JQL `project = <KEY> AND Status = "Ready" ORDER BY priority DESC, created ASC`.
+   - Full JQL: use as-is. If it does not include a `Status` clause, append `AND Status = "Ready"`.
+2. Resolve Atlassian cloud ID via `getAccessibleAtlassianResources`.
+
+### Phase 2 — Find Ready tickets
+
+Run the JQL via `searchJiraIssuesUsingJql`. Capture each ticket's: key, summary, issue type, priority, assignee, parent (epic), labels, components.
+
+If empty, report `"No tickets with Status=Ready. Nothing to do."` and exit. This is the common idle case.
+
+### Phase 3 — Process each Ready ticket (serial)
+
+#### 3a. Claim
+
+Transition the ticket from `Ready` to `In Progress` via `transitionJiraIssue`.
+- Use `getTransitionsForJiraIssue` to find the transition ID for `In Progress`.
+- Post a `[claude-build-intake]` comment via `addCommentToJiraIssue`: `"Claimed by Claude. Starting build."`
+- This is the idempotency lock — a re-entrant cycle's `Status = Ready` filter will not see this ticket again.
+
+If the transition fails (permission, missing transition, race), log under "Errors" in the cycle summary and skip this ticket. **Do not invoke the build flow on a ticket you didn't successfully claim.**
+
+#### 3b. Run the build flow
+
+Invoke the `jira-agent` (existing per-ticket lifecycle agent) with the ticket key. `jira-agent` owns:
+- Reading the full ticket graph (`jira-read-ticket`)
+- Running its own pre-flight quality gate (`jira-verify`)
+- Running ticket triage (`ticket-triage`)
+- Routing to the appropriate flow (Build / Fix / Investigate / Improve based on type)
+- Posting progress comments via `jira-sync`
+- Posting evidence via `jira-evidence`
+
+Wait for `jira-agent` to return. Capture its outcome:
+- **Success** — PR is ready (open or merged); evidence posted; ready for next status.
+- **Blocked by jira-verify pre-flight gate** — `jira-agent` itself transitions the ticket to `Blocked` and reassigns to Reporter. This is correct and expected — let it stand. Record the outcome and move on.
+- **Blocked by ticket-triage ambiguities** — `jira-agent` posts findings and stops. The ticket stays in `In Progress`. Surface to human; do not auto-transition. Record under "Errors" with reason `"Triage found ambiguities — see comments on <ticket-key>"`.
+- **Errored** — exception, missing config, etc. Leave the ticket in `In Progress` for human investigation. Record under "Errors" with the exception summary.
+
+#### 3c. Transition to On Dev (only on Success)
+
+If `jira-agent` returned Success:
+1. Use `getTransitionsForJiraIssue` to find the transition ID for `On Dev` (or the configured next-after-build status).
+2. Transition via `transitionJiraIssue`.
+3. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. Transitioned to On Dev."`
+
+For any non-Success outcome, do NOT transition. The ticket sits in `In Progress` (or wherever `jira-agent` left it for the Blocked case) — the cycle's job is done; humans take it from there.
+
+#### 3d. Continue
+
+Move to the next Ready ticket. One ticket failing does not stop others.
+
+### Phase 4 — Summary report
+
+```text
+## jira-build-intake summary
+
+Query: <JQL or project key>
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+Tickets processed: <n>
+- On Dev (build complete, PR ready): <n>
+  - <ticket-key> <summary> → PR <URL>
+- Blocked (pre-flight verify failed): <n>
+  - <ticket-key> <summary> — see ticket comments
+- Held (triage found ambiguities): <n>
+  - <ticket-key> <summary> — see ticket comments
+- Errors: <n>
+  - <ticket-key> <summary> — <reason>
+
+Total PRs opened: <n>
+```
+
+## Idempotency & safety
+
+- **Claim-first ordering**: `In Progress` set BEFORE `jira-agent` invocation — no double-pickup.
+- **No writes outside the lifecycle**: this skill only transitions `Ready → In Progress` and `In Progress → On Dev`. Every other status change is owned by `jira-agent` (which suggests transitions but only auto-transitions on the verify-FAIL path).
+- **Failure isolation**: per-ticket exceptions caught and recorded; the cycle continues.
+- **Single cycle per query**: do not run two `jira-build-intake` cycles in parallel against overlapping queries — concurrent claims could race. The scheduling layer (when added) is responsible for serialization.
+- **Never invent a transition**: if `In Progress` or `On Dev` aren't valid transitions in the project's workflow, stop and report rather than guessing alternative names.
+
+## Configuration
+
+Status names default to `Ready`, `In Progress`, `On Dev`. If a project uses different names (`Open` instead of `TODO`, `In Development` instead of `In Progress`, `Code Review` instead of `On Dev`), pass overrides in `$ARGUMENTS` as `claim_status="In Development" done_status="Code Review"`.
+
+If a `Ready` status does not exist in the JIRA project's workflow, this skill cannot run. The remediation is to add `Ready` to the project workflow scheme — JIRA admin task, not something this skill can do.
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `JIRA_PROJECT` | (from `$ARGUMENTS`) | Project key for the default JQL |
+| Status: queue | `Ready` | The status that signals "human says this is buildable" |
+| Status: claim | `In Progress` | The intermediate status the agent sets on pickup |
+| Status: done | `On Dev` | The status set after a successful build |
+
+## Rules
+
+- Never transition a ticket the cycle didn't claim. The `In Progress` transition is the signature of cycle ownership.
+- Never bypass `jira-agent` to do build work directly. `jira-agent` owns the per-ticket lifecycle (read, verify, triage, route, sync, evidence). This skill is the dispatcher, not the builder.
+- Never auto-transition past `On Dev`. Downstream statuses (`On QA`, `Done`) are owned by QA / product / a future verification-intake skill — not this one.
+- If the ticket has no Validation Journey or no sign-in credentials in its description, `jira-agent`'s pre-flight verify will catch it and transition to `Blocked` — **don't try to fix the ticket from here**. Pre-flight gating is `jira-agent`'s job; running build work on a thin ticket produces broken work.
+- On any unexpected response from `jira-agent` (status it doesn't claim, missing PR URL on success, etc.), record as Error and surface — never assume.

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

@@ -6,18 +6,22 @@ allowed-tools: ["Read", "Glob", "LS", "Skill", "mcp__atlassian__getVisibleJiraPr
 
 # Create JIRA Issues from $ARGUMENTS
 
-Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all mandatory quality gates.
+Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans structure only — every individual ticket write is delegated to `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. **Determine Structure**:
+1. **Analyze**: Read $ARGUMENTS to understand scope.
+2. **Extract source artifacts**: invoke the `jira-source-artifacts` skill, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain per its rules. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `product-walkthrough` skill to capture current behavior, design-vs-product divergence, and reuse candidates. Skip 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
-3. **Create Issues** with hierarchy:
-   ```
+5. **Plan hierarchy**:
+   ```text
    Epic → User Story → Tasks (test, implement, document, cleanup)
    ```
+6. **Delegate every write to `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 `jira-source-artifacts` inheritance rules) and the walkthrough findings (under `## Current Product`). See "Delegation to jira-write-ticket" below.
+7. **Run the artifact preservation gate** (`jira-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
 
@@ -81,33 +85,17 @@ h3. Assertions
 4. **Assertions are testable statements** — "Health check returns 200 with status ok" not "API works"
 5. **Prerequisites include environment setup** — Database connection, env vars, running services
 
-## Source Artifact Preservation
-
-If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
+## Source Artifacts
 
-Rules:
+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.
 
-1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
-2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
-3. **Stories inherit by domain**: frontend stories get `ui-design` + `ux-flow` + `reference`; backend gets `data` + `reference`; infra gets `ops` + `reference`. When ambiguous, err on the side of inclusion.
-4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
-5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
+**Invoke the `jira-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 — invoke the skill so any rule change propagates uniformly.
 
 When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
 
-**Classification disambiguation** (applied during extraction):
-- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
-- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
-- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
-
-**Source precedence** (must be recorded on every ticket carrying design artifacts):
-- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
-- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
-- Flow and interaction (navigation, transitions, state changes) come from **prototypes** (`ux-flow`).
-- API / data shape comes from **`data` artifacts**.
-- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
+## Live Product Walkthrough
 
-**Existing-component reuse** (applies to every UI-touching ticket): the story description must instruct the implementer to locate the closest existing component in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
+When the work touches existing user-facing surfaces, invoke the `product-walkthrough` skill before drafting tickets. The walkthrough 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
 
@@ -120,10 +108,45 @@ Each issue must clearly communicate to:
 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.
-
 ## Delegation to jira-write-ticket
 
-For every individual ticket that will be created, delegate to the `jira-write-ticket` skill rather than calling `mcp__atlassian__createJiraIssue` directly. `jira-write-ticket` enforces description quality (Gherkin acceptance criteria, stakeholder/developer/assistant sections), relationship discovery (`blocks`, `is blocked by`, `relates to`, remote PR/Confluence/dashboard links), epic parent validation, and post-create verification.
+**Mandatory.** Every ticket created by this skill MUST go through `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.
+
+`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 `jira-write-ticket` for the epic. Capture the returned key.
+2. For each story, invoke `jira-write-ticket` with the epic key as the epic parent. Capture each story key.
+3. For each sub-task, invoke `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 — `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 `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 Phase 5.5-style preservation check after all writes complete
 
-This skill's role is to analyze the input and decide the hierarchy (which epics, which stories, which tasks, in what parent-child structure). `jira-write-ticket` handles the actual write with full quality gates.
+It does not own the actual JIRA write — that's `jira-write-ticket`'s job.

package/plugins/lisa/skills/jira-source-artifacts/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: jira-source-artifacts
+description: "Canonical taxonomy and rules for handling source artifacts (Figma, Lovable, Loom, screenshots, design docs, data samples) when generating or evaluating JIRA tickets. Defines: (1) artifact domains, (2) classification rules per tool, (3) source precedence (which artifact is authoritative for which question), (4) inheritance from epic to story to sub-task, (5) cross-axis conflict handling. Invoke this skill from any flow that extracts, attaches, or reasons about external design/UX/data artifacts so the rules don't drift across skills."
+allowed-tools: []
+---
+
+# JIRA Source Artifact Taxonomy and Rules
+
+This skill is doctrine, not action — it defines the rules. Skills that need to extract, classify, attach, or reason about external artifacts (design files, prototypes, recordings, data samples) invoke this skill to load the taxonomy and apply it.
+
+The reason this lives in one place: silent drift across skills is the failure mode this body of rules exists to prevent. If the rules differ between `notion-to-jira`, `jira-create`, and `jira-write-ticket`, agents will silently route artifacts wrong and developers will lose source of truth. Edit here, propagate everywhere.
+
+## 1. Domains
+
+Every artifact is classified into exactly one domain. The domain determines what the artifact is the source of truth for, and which tickets inherit it.
+
+| Domain | What it defines | Examples |
+|--------|-----------------|----------|
+| `ui-design` (mocks) | **Visual treatment only** — layout, spacing, typography, color, iconography | Figma design frames, Framer static frames, bare screenshots, mockup PNGs |
+| `ux-flow` (prototypes) | **Interaction and flow only** — navigation, transitions, state changes, timing, empty/error/loading states | Lovable output, Loom walkthroughs, Figma prototype links, annotated screenshots, Miro/Mural flow diagrams, user journey maps |
+| `data` | Request/response shape, schema constraints, contracts | Example JSON, SQL schemas, GraphQL snippets, API contracts, sample payloads |
+| `ops` | Deployment / runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
+| `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs, RFCs |
+
+## 2. Classification rules per tool
+
+These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped or misrouted context.
+
+- **Figma**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume; inspect the URL.
+- **Figma file with both design frames and a prototype**: emit two entries — one `ui-design` for the file, one `ux-flow` for the prototype URL — so both propagate correctly.
+- **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD body, not from Lovable.
+- **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's purely a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit).
+- **Screenshot**: bare unannotated screenshot → `ui-design`. Screenshot with arrows between frames, flow labels, or numbered steps → `ux-flow`. Side-by-side gallery of state variants (empty/error/loading) → `ui-design` with the state variants noted.
+- **Confluence / Notion peer / Google Doc**: `reference` unless it is specifically a runbook (`ops`) or contains canonical API contracts (`data`).
+- **Grafana / Datadog / Sentry**: `ops`.
+- **Code blocks with example payloads** (JSON, SQL, GraphQL, cURL): `data`.
+
+When an artifact could plausibly fit multiple domains and the rules above don't disambiguate, err on the side of inclusion — emit it under both, or use the broader domain. Misclassification is caught downstream by the preservation gate; underclassification is silent drop.
+
+## 3. Source precedence
+
+When artifacts disagree, silent reconciliation is a known failure mode. The rules below define which source wins which question. **Record this precedence on every ticket that carries design artifacts** (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't reconcile silently.
+
+| Question | Authoritative source |
+|----------|---------------------|
+| Does this field exist? Is it required? Who can see/edit it? What validation applies? Permission rules, edge cases, data constraints? | **Description / PRD body** (business rules) |
+| What does it look like — layout, spacing, typography, color, iconography? | **Mocks (`ui-design`)** |
+| How does it flow — navigation, transitions, state changes, timing, empty/error/loading states? | **Prototypes (`ux-flow`)** |
+| Where does the data come from, what shape is it, what are the API contracts? | **`data` artifacts** |
+| Where does it run, who's on call, what's the dashboard? | **`ops` artifacts** |
+
+## 4. Cross-axis conflict handling
+
+Conflicts MUST be surfaced under `## Open Questions` on the affected ticket — never silently reconciled.
+
+- Mock shows a field the description doesn't mention → BLOCKER: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation, permissions)."
+- Description mandates behavior the prototype contradicts → BLOCKER: "PRD says Y, prototype shows Z; which is correct?"
+- Prototype shows a flow the mocks don't cover (e.g., an error state) → Note: "Error state flow from prototype; no mock exists. Use existing error component or request mock."
+- Multiple artifacts of the same domain disagree (two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
+- Lovable output without a description covering business rules → BLOCKER: "Business rules missing. Lovable's embedded logic is not authoritative; PRD must explicitly state required fields, validation, permissions, and edge cases."
+
+## 5. Coverage smells
+
+Incomplete artifact sets are a common root cause of implementation drift. Surface these on the epic when extracting:
+
+- **Zero artifacts on a non-trivial PRD**: almost always an extraction bug, not a design decision. Say so explicitly.
+- **`ux-flow` present, `ui-design` absent**: flag "missing UI mocks". UI will be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth.
+- **`ui-design` present, `ux-flow` absent**: flag "missing UX prototype". UX will be inferred from static mock states (empty/error/loading/hover) — any flow not explicitly depicted must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
+
+## 6. Inheritance: epic → story → sub-task
+
+Artifacts attach as Jira remote links and propagate down the hierarchy.
+
+- **Epic**: gets EVERY artifact, regardless of domain. The epic is the canonical hub — anyone working on the epic or its descendants must reach the full set from one place. No filtering.
+- **Story**: inherits the artifacts whose domain matches its scope:
+
+  | Story type | Inherits domains |
+  |------------|------------------|
+  | Frontend / UI | `ui-design`, `ux-flow`, `reference` |
+  | Backend / API / data model | `data`, `reference` |
+  | Infrastructure | `ops`, `reference` |
+  | Mixed / setup ("X.0") | All domains |
+
+  When classification is ambiguous, err on the side of inclusion — a developer can ignore an extra link, but they can't follow one that wasn't attached.
+
+- **Sub-task**: inherits via the parent story link. Do NOT re-attach the same artifacts on every sub-task — that creates noise. Only attach an artifact directly on a sub-task when the sub-task depends on something the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame the broader story doesn't cite).
+
+## 7. Existing-component reuse (UI-touching tickets)
+
+Mocks define visual *intent*, not implementation shortcut. Every UI-touching ticket description must include:
+
+> Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling — flag the design-vs-code divergence as a discussion item on this ticket rather than pixel-matching from scratch.
+
+If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation. Lovable-generated components are never the reuse target — always use the project's own components.
+
+## 8. Preservation gate (run after creating tickets)
+
+Before declaring done, verify every extracted artifact is reachable from the created tickets.
+
+1. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
+2. For every artifact:
+   - It MUST appear on the epic it belongs to (no exceptions).
+   - It SHOULD appear on at least one story whose scope matches its domain (except `reference`-domain artifacts, which may be epic-only if no story is domain-matched).
+3. Any artifact with zero references anywhere, or missing from its epic: FAIL LOUDLY — list the dropped artifacts with domain, title, and source page; surface to the human; re-attach before continuing.
+4. If classification looks misrouted (e.g., a Figma link landed on a backend story and nowhere else), surface the misroute and offer to re-propagate.
+
+Skipping this gate is the most common cause of silent artifact loss. Do not skip it.

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

@@ -0,0 +1,224 @@
+---
+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-jira runs it during PRD intake) call this skill so the bar can never drift."
+allowed-tools: ["Bash", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getIssueLinkTypes", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Validate JIRA Ticket: $ARGUMENTS
+
+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 (`jira-write-ticket` for pre-write gating, `notion-to-jira` for PRD dry-run, `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" }]
+```
+
+If the caller passes only a ticket key, fetch the ticket via `mcp__atlassian__getJiraIssue`, derive the same fields from the fetched data, 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.
+
+### 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}`, description must contain `h2. Repository` naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation to split.
+
+Story / Epic / Spike / Improvement: skipped (may span repos).
+
+#### 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 jira-add-journey to append the section after create"`. Callers like `jira-write-ticket` know to chain `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 `notion-to-jira` 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 `jira-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.
+
+### Feasibility Gates (require JIRA lookups; skip in dry-run if requested)
+
+#### F1 — Issue type valid in project
+
+Call `mcp__atlassian__getJiraProjectIssueTypesMetadata` and confirm `issue_type` exists in `project_key`.
+
+#### F2 — Epic parent exists and is an Epic
+
+When `parent_key` is set for non-Sub-task: fetch via `mcp__atlassian__getJiraIssue`, 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`, call `mcp__atlassian__getJiraIssue` to confirm the key resolves. Flag broken keys.
+
+#### F4 — Required custom fields populated
+
+`mcp__atlassian__getJiraProjectIssueTypesMetadata` returns 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 and derive the spec from the fetched fields. Otherwise parse the YAML spec.
+2. Resolve cloud ID via `mcp__atlassian__getAccessibleAtlassianResources` if any feasibility gate will run.
+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>
+
+### 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>
+### Remediation
+- <gate-id>: <concrete fix the caller can apply or surface to the user>
+- <gate-id>: <concrete fix>
+```
+
+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.
+
+## Rules
+
+- Never write to JIRA. The `allowed-tools` list intentionally excludes `createJiraIssue`, `editJiraIssue`, `createIssueLink`, `addCommentToJiraIssue`.
+- 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 remediation lines must be concrete and actionable — the dry-run path turns each one into a Notion comment, so vague guidance is useless.