@codyswann/lisa 1.94.0 → 1.96.0

package/plugins/lisa/skills/notion-to-jira/SKILL.md

@@ -14,6 +14,50 @@ description: >
 Convert a Notion PRD into a structured JIRA ticket hierarchy: Epics > Stories > Sub-tasks.
 Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
 
+## Modes
+
+This skill supports two modes, controlled by a `dry_run` flag in `$ARGUMENTS`:
+
+- **`dry_run: false`** (default — full mode): run all phases, write tickets via `jira-write-ticket`, run the preservation gate, report.
+- **`dry_run: true`** (planning + validation only — no writes): run Phases 1, 1.5, 1.6, 2, 3, 4 to plan the hierarchy and draft each ticket spec, then call `jira-validate-ticket` (with `--spec-only`) on every drafted ticket. Aggregate the per-ticket validator reports into a single dry-run report. **Skip Phase 5 (sub-task creation), Phase 5.5 (preservation gate), and Phase 6 (results report)** — none of those make sense without writes. Return the dry-run report so the caller (e.g. `notion-prd-intake`) can decide whether to proceed.
+
+Dry-run output format:
+
+```text
+## notion-to-jira dry-run: <PRD title>
+
+### Planned hierarchy
+- Epic: <summary>
+  - Story 1.1: <summary>
+    - Sub-task [<repo>]: <summary>
+    - ...
+  - Story 1.2: ...
+
+### Per-ticket validation
+- <ticket-id>: PASS | FAIL — <count> failures
+  - <gate-id>: <one-line reason and remediation>
+
+### Verdict: PASS | FAIL
+### Total failures: <n>
+```
+
+The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJiraIssue`. It also never sets a Notion status — that is the orchestrating skill's responsibility.
+
+## Hard Rule: All Writes Go Through `jira-write-ticket`
+
+**Every JIRA ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `jira-write-ticket` skill. Never call `mcp__atlassian__createJiraIssue`, `mcp__atlassian__editJiraIssue`, `mcp__atlassian__createIssueLink`, or any other Atlassian write tool directly from this skill or from any sub-agent it spawns.**
+
+`jira-write-ticket` enforces gates this skill does not:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation
+- Explicit issue-link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Single-repo scope check on Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+Bypassing `jira-write-ticket` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. This is the most common failure mode this skill has had — calling `createJiraIssue` directly is a regression, not an optimization. The Atlassian read tools (`getJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssueRemoteIssueLinks`, `getAccessibleAtlassianResources`, `getJiraProjectIssueTypesMetadata`, `getVisibleJiraProjects`) ARE allowed for context gathering and the Phase 5.5 preservation gate.
+
 ## Input
 
 A Notion PRD URL. The PRD is expected to have:
@@ -67,66 +111,23 @@ PRDs typically reference external design, UX, and data artifacts (Figma files, L
    - Embedded images and file attachments on the page itself
    - Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
 
-2. **Classify each artifact by domain**. The split matters — each domain is the source of truth for different implementation decisions:
-
-   | 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 | Example JSON, SQL schemas, GraphQL snippets, API contracts |
-   | `ops` | Deployment/runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
-   | `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs |
-
-3. **Apply disambiguation rules** when an artifact could fit multiple domains. These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped context.
-
-   - **Figma URL**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, or has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume.
-   - **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat Lovable strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD description, not from Lovable.
-   - **Screenshot with annotations** (arrows between frames, flow labels, numbered steps): `ux-flow`. A bare unannotated screenshot: `ui-design`. A side-by-side gallery of state variants (empty/error/loading): `ui-design` with state variants noted.
-   - **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's only a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit from it).
-   - **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.
+2. **Classify each artifact and apply taxonomy rules** by invoking the `jira-source-artifacts` skill. That skill is the single source of truth for: domains (`ui-design` / `ux-flow` / `data` / `ops` / `reference`), per-tool classification rules (Figma `/proto/` vs design, Lovable as `ux-flow`, Loom, screenshots), and coverage smells. Do not restate the rules here — invoke the skill so any drift in the rules propagates uniformly.
 
-4. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable ("Figma URL contains `/proto/` → ux-flow"). The `source_page` lets you trace each reference back to where it appeared in the PRD.
+3. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable ("Figma URL contains `/proto/` → ux-flow"). The `source_page` lets you trace each reference back to where it appeared in the PRD.
 
-5. **Surface coverage smells** — incomplete artifact sets are a common root cause of implementation drift:
-   - **Zero artifacts** on a non-trivial PRD: almost always an extraction bug, not a design decision. Say so explicitly.
-   - **Prototype but no mock** (`ux-flow` present, `ui-design` absent): flag "missing UI mocks". UI will have to be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth. Record the smell on the epic.
-   - **Mocks but no prototype** (`ui-design` present, `ux-flow` absent): flag "missing UX prototype". UX will have to be inferred from static mock states (empty/error/loading/hover) — any flow that isn't explicitly depicted in the mocks must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
-   - **Lovable output without a description covering business rules**: flag "business rules missing". Lovable's embedded logic is not authoritative; the PRD description must explicitly state required fields, validation, permissions, and edge cases.
+4. **Surface coverage smells** as defined in `jira-source-artifacts` §5 (zero artifacts, prototype-without-mock, mock-without-prototype, Lovable-without-business-rules). Record any detected smells on the epic.
 
 ### Phase 1.6: Source Precedence & Conflict Resolution
 
-Different artifact domains answer different questions. When they disagree, silent reconciliation is a known failure mode — these rules must be encoded on the tickets and respected during implementation.
+Source precedence rules and cross-axis conflict handling are defined in `jira-source-artifacts` §3 and §4. Apply them during ticket synthesis: every conflict between artifacts must be recorded under `## Open Questions` on the affected ticket, never silently reconciled.
 
-**Authoritative source by question**:
+The existing-component reuse expectation (mocks define visual intent, not implementation shortcut) is defined in `jira-source-artifacts` §7. Encode it on every UI-touching story.
 
-| Question | Authoritative source |
-|----------|---------------------|
-| Does this field exist? Is it required? Who can see/edit it? What validation applies? What are the edge cases, permission rules, 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** |
+### Phase 2: Codebase + Live Product Research
 
-**Cross-axis conflicts must be surfaced, not reconciled silently**:
+Two complementary inputs ground PRD analysis: the **code** (what's there to reuse / extend) and the **live product** (what users see today). Skipping either produces tickets that misjudge the change.
 
-- Mock shows a field the description doesn't mention → BLOCKER on the story: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation)."
-- 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 on the story: "Error state flow from prototype; no mock exists for the error UI. Use existing error component or request mock."
-- Multiple artifacts of the same domain disagree (e.g., two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
-
-Record every conflict on the ticket description under a `## Open Questions` subsection so the developer picking up the ticket sees it before writing code.
-
-**Existing-component reuse (applies to `ui-design` consumers)**:
-
-Mocks define *visual intent*, not *implementation shortcut*. Before a developer builds UI from a mock, they must search the codebase for the closest-matching existing component. Encode this expectation on every UI-touching story:
-
-- Story description includes: "Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the Figma mock specifies different styling — flag the design-vs-code divergence as a discussion point on this ticket rather than pixel-matching Figma 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.
-
-### Phase 2: Codebase Research (if needed)
-
-If the session doesn't already have codebase context, explore the repos to understand what exists.
-Use Explore agents for repos not yet examined. Skip repos already explored in the current session.
+**2a. Codebase research.** If the session doesn't already have codebase context, explore the repos to understand what exists. Use Explore agents for repos not yet examined. Skip repos already explored in the current session.
 
 Key things to look for:
 - Existing entities/modules that overlap with the PRD
@@ -134,41 +135,65 @@ Key things to look for:
 - Data model gaps the PRD requires (new fields, new entities)
 - The tech stack per repo (framework, ORM, UI library, deployment)
 
+**2b. Live product walkthrough.** If the PRD touches existing user-facing surfaces (modifies a screen, adds something next to existing functionality, fixes current behavior, re-styles an existing flow), invoke the `product-walkthrough` skill against `E2E_BASE_URL` using the test user from config. This grounds the ticket plan in what's actually shipped — design-vs-current-product divergence, reuse candidates, and behavioral surprises that the PRD didn't anticipate become inputs to ticket creation rather than discoveries during implementation.
+
+Skip 2b only when the work is purely backend with no user-visible surface, or affects a screen that does not yet exist in dev/prod.
+
+Walkthrough findings are attached to the originating Notion PRD as a comment ("Current product walkthrough — `<route>`") and inherited onto the resulting epic / stories under a `## Current Product` subsection.
+
 ### Phase 3: Create Epics
 
-Create one Epic per PRD epic using the JIRA project key from config. Each Epic description should include:
-- Summary of the epic from the PRD
-- List of user stories it contains
-- Key decisions from comments (with attribution)
-- Blockers and open questions
-- Dependencies on other epics or PRDs
-- A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
+> **Mode guard**: In `dry_run: true` mode, do not invoke `jira-write-ticket` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `jira-validate-ticket --spec-only`. Record the drafted spec (including a placeholder epic key like `DRY-RUN-EPIC-1`) for Phase 4 to use as parent references. In `dry_run: false` mode (default), proceed as described below.
 
-Use `contentFormat: "markdown"` for all descriptions.
+For each PRD epic, **invoke the `jira-write-ticket` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
 
-**Attach every artifact from Phase 1.5 as an Epic remote link** — regardless of domain. The epic is the canonical hub, and anyone working on the epic or its descendants must be able to reach the full set from one place. No filtering at the epic level.
+- `project_key`: from `JIRA_PROJECT` config
+- `issue_type`: `Epic`
+- `summary`: epic title from the PRD
+- `description_body`: a draft of the 3-audience description containing:
+  - **Context / Business Value**: epic summary from the PRD, originating Notion URL, business outcome
+  - **Technical Approach**: cross-cutting integration points and constraints surfaced in Phase 2 codebase research
+  - List of user stories the epic contains
+  - Key decisions from comments (with attribution)
+  - Blockers and open questions
+  - Dependencies on other epics or PRDs
+  - A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
+- `artifacts`: the full Phase 1.5 artifact list — every artifact, regardless of domain. The epic is the canonical hub, and anyone working on the epic or its descendants must be able to reach the full set from one place. No filtering at the epic level. `jira-write-ticket` Phase 4c attaches them as remote links.
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
+
+Capture the returned epic key — Phase 4 needs it as the parent for stories.
 
 ### Phase 4: Create Stories
 
-For each Epic, create Stories:
+> **Mode guard**: In `dry_run: true` mode, do not invoke `jira-write-ticket` in this phase. Instead, draft each story spec and validate it with `jira-validate-ticket --spec-only`. Use placeholder keys (e.g. `DRY-RUN-STORY-1.1`) for any downstream references. In `dry_run: false` mode (default), proceed as described below.
+
+For each Epic, plan two kinds of stories:
 - **One "X.0 Setup" story** for data model and infrastructure prerequisites (new entities, migrations, new fields, infrastructure like S3 buckets or SQS queues)
 - **One story per user story** from the PRD (numbered to match the PRD)
 
-**Story naming convention**: Prefix with a short code derived from the PRD title:
+**Story naming convention**: Prefix the summary with a short code derived from the PRD title:
 - "Contract Upload" -> `[CU-1.1]`
 - "Squad Planning" -> `[SP-1.1]`
 - Use your judgment for other PRDs
 
-Each story description should include:
-- The user story statement from the PRD
-- Acceptance criteria (from functional requirements)
-- Technical notes from engineering comments
-- Blockers with recommendation + alternatives (if any)
-- A **Source Artifacts** section listing the artifacts inherited from the epic that match this story's scope (see propagation rules below)
+For each story, **invoke `jira-write-ticket`** with:
 
-Set `parent` to the Epic key to link stories to their epic.
+- `project_key`: from `JIRA_PROJECT` config
+- `issue_type`: `Story`
+- `epic_parent`: the Epic key captured in Phase 3 (mandatory — `jira-write-ticket` rejects non-bug, non-epic tickets without an epic parent)
+- `summary`: prefixed per the naming convention above
+- `description_body`: a draft of the 3-audience description containing:
+  - **Context / Business Value**: the user story statement from the PRD
+  - **Technical Approach**: notes from engineering comments and Phase 2 codebase research
+  - **Acceptance Criteria** (Gherkin) derived from the functional requirements — `jira-write-ticket` will reject prose-only acceptance criteria
+  - Blockers with recommendation + alternatives (if any), under `## Open Questions`
+  - A **Source Artifacts** section listing the artifacts inherited from the epic that match this story's scope (see propagation rules below)
+- `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below — `jira-write-ticket` Phase 4c attaches them as remote links
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
 
-**Inherit domain-matching artifacts as story remote links**. For each story, attach the Phase 1.5 artifacts whose domain matches the story's scope:
+Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
+
+**Inherit domain-matching artifacts as story remote links**. For each story, the artifact set passed to `jira-write-ticket` should be the Phase 1.5 artifacts whose domain matches the story's scope:
 
 | Story type | Inherits domains |
 |------------|------------------|
@@ -181,10 +206,10 @@ When classification is ambiguous, err on the side of inclusion — a developer c
 
 ### Phase 5: Create Sub-tasks
 
-Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency.
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `jira-write-ticket` for each sub-task — no agent may call `createJiraIssue` directly.** This is non-negotiable; see the Agent Prompt Template at the bottom of this skill for the exact instructions to pass.
 
 Each sub-task MUST:
-1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`. `jira-write-ticket` enforces single-repo scope on Sub-task; cross-repo sub-tasks will be rejected and must be split before delegation.
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
 
 **Verification plan examples by stack:**
@@ -192,28 +217,24 @@ Each sub-task MUST:
 - **Frontend web**: Playwright browser tests (login with test user, navigate, interact, screenshot)
 - **Infrastructure**: `cdk synth` / `terraform plan` verification, CLI checks after deploy
 
-Use the test user credentials from config for all verification plans.
+Use the test user credentials from config for all verification plans. The credentials are passed to `jira-write-ticket` as the sign-in account so it can record them in the description per its own rules.
+
+For each sub-task, the spawned agent invokes `jira-write-ticket` with `issue_type: "Sub-task"` and `parent` set to the Story key. The Story key is the parent — the epic relationship is inherited transitively.
 
-Set `parent` to the Story key. Use `issueTypeName: "Sub-task"`.
+Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task — that creates noise. The only exception is when a sub-task depends on an artifact that the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame that the broader story doesn't cite) — in that case, pass the specific artifact in the `artifacts` parameter to `jira-write-ticket`.
 
-Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not re-attach the same remote links on every sub-task — that creates noise. The only exception is when a sub-task depends on an artifact that the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame that the broader story doesn't cite) — in that case, attach the specific artifact directly.
+### Phase 5.5: Artifact Preservation Gate (mandatory)
 
-### Phase 5.5: Artifact Preservation Gate
+Run the preservation gate defined in `jira-source-artifacts` §8 against the artifacts extracted in Phase 1.5 and the tickets just created. Do NOT restate or modify the gate logic here — invoke the rules from `jira-source-artifacts` so any rule change propagates uniformly.
 
-Before reporting, verify that every artifact extracted in Phase 1.5 is reachable from the created tickets. This gate exists because silent artifact loss is the failure mode this skill is designed to prevent.
+To run the gate, this skill must:
 
-1. Pull the remote links of every epic and story created in this run (via the JIRA API).
-2. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
-3. For every artifact from Phase 1.5:
-   - 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).
-4. If any artifact has zero references anywhere, or is missing from its epic, FAIL LOUDLY:
-   - List each dropped artifact with its domain, title, and source page.
-   - State why it was dropped (domain classification error, propagation skipped, attach failure).
-   - Ask the human to confirm the drop or point at the right epic/story, then re-attach before continuing.
-5. If classification seems misrouted (e.g., a Figma link ended up on a backend story and nowhere else), surface the misroute and offer to re-propagate.
+1. Pull the remote links of every epic and story created in this run via `mcp__atlassian__getJiraIssueRemoteIssueLinks`.
+2. Apply the §8 preservation matrix and verdict rules.
+3. If the gate fails: list each dropped/misrouted artifact (domain, title, source page, why it was dropped) and either re-attach via `jira-write-ticket` (UPDATE mode) or stop and ask the human. Never silently proceed past a gate failure.
+4. If the gate passes: print the matrix compactly and proceed to Phase 6.
 
-Do NOT skip this gate. If every artifact is preserved, print the matrix compactly and proceed to Phase 6.
+This gate is not optional. Skipping it is the failure mode the architecture exists to prevent.
 
 ### Phase 6: Report Results
 
@@ -244,19 +265,40 @@ Common blocker categories:
 
 ## Agent Prompt Template for Sub-task Creation
 
-When delegating to agents, provide this context:
+When delegating to agents, provide this context. **The "MUST invoke jira-write-ticket" instruction is load-bearing — do not edit it out when adapting this template.**
 
 ```text
 Create JIRA sub-tasks in the [PROJECT] project at [CLOUD_ID].
-Use issueTypeName "Sub-task" and set parent to the story key.
-Use contentFormat "markdown".
 
-Test user info: [credentials from config]
+CRITICAL: For each sub-task, invoke the `jira-write-ticket` skill via the Skill tool.
+Do NOT call `mcp__atlassian__createJiraIssue` directly. The `jira-write-ticket` skill
+enforces required quality gates (Gherkin acceptance criteria, 3-audience description,
+single-repo scope, sign-in/environment fields, post-create verification). Bypassing it
+produces broken tickets that downstream skills (triage, journey, evidence) cannot use.
+
+For each sub-task, invoke `jira-write-ticket` with:
+- issue_type: "Sub-task"
+- parent: the parent story key
+- project_key: [PROJECT]
+- summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria)
+- gherkin_acceptance_criteria: derived from the story's functional requirements
+- sign_in_account: [test user credentials from config — name + role + how to obtain]
+- target_environment: "dev"
+- empirical_verification_plan: real user-like verification (curl + auth token,
+  Playwright browser flow, CLI check after deploy) using the test credentials.
+  NOT unit tests, linting, or typechecking.
 
 Each sub-task must:
-1. Be scoped to ONE repo only
-2. Include an **Empirical Verification Plan** section
-3. Include the repo in brackets in the summary
+1. Be scoped to ONE repo only — repo named in brackets in the summary
+2. Include the Empirical Verification Plan in the description
+3. Be created via `jira-write-ticket`, not via direct MCP calls
+
+If `jira-write-ticket` rejects a sub-task (cross-repo scope, missing Gherkin, missing
+sign-in, etc.), fix the input and re-invoke. Do NOT fall back to a direct
+`createJiraIssue` call to bypass the gate.
+
+Test user info: [credentials from config]
 
 [Then list all sub-tasks grouped by parent story with details]
 ```

package/plugins/lisa/skills/prd-ticket-coverage/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: prd-ticket-coverage
+description: "Verifies that every requirement in a Notion PRD is covered by at least one created JIRA ticket — no silent drops. Parses the PRD into atomic items (goals, user stories, functional/non-functional requirements, acceptance criteria, important notes), maps each to the created tickets, and produces a coverage matrix and verdict (COMPLETE / COMPLETE_WITH_SCOPE_CREEP / GAPS_FOUND / NO_TICKETS_FOUND). Used by notion-prd-intake post-write to gate the Status=Ticketed transition; can also be invoked standalone for after-the-fact audits."
+allowed-tools: ["Skill", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-get-comments", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# PRD Ticket Coverage Audit: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A PRD URL alone — auto-discover created tickets via the PRD's epic remote link.
+2. A PRD URL plus an explicit list of ticket keys — `<PRD URL> tickets=[KEY-1,KEY-2,...]`. Use this when called from `notion-prd-intake` (which knows the keys it just created).
+
+Verify that every atomic item in the PRD is covered by at least one of the listed/discovered JIRA tickets. The output gates whether the PRD's `Status` should remain `Ticketed` or revert to `Blocked`.
+
+## Why this exists
+
+Per-ticket gates (`jira-validate-ticket`) prove each created ticket is well-formed in isolation. They do NOT prove the *set* of created tickets is complete relative to the source PRD. Silent drops happen — an agent generates 8 tickets when the PRD called for 9, and nothing notices. This skill is the catch.
+
+## Phases
+
+### Phase 1 — Resolve inputs
+
+1. Parse `$ARGUMENTS`:
+   - PRD URL → extract page ID.
+   - Optional `tickets=[...]` → list of explicit ticket keys.
+2. Fetch the PRD via `notion-fetch` with `include_discussions: true`. Capture: title, body, child Epic pages, all comment threads.
+3. If the PRD has child Epic sub-pages (a multi-epic PRD like Home revamp), fetch each in parallel with `include_discussions: true`. The audit walks the full PRD tree.
+4. If `tickets=[...]` not provided, locate the JIRA epic by:
+   - Looking for a JIRA URL in the PRD body, comments, or the PRD's most recent "Ticketed by Claude" comment posted by `notion-prd-intake`.
+   - Searching JIRA via `searchJiraIssuesUsingJql` for an epic whose summary or description references the PRD title or page ID.
+   - If no epic found, return verdict `NO_TICKETS_FOUND` with a clear remediation — coverage cannot be assessed without the ticket set.
+5. Once the epic is known, fetch all child stories and sub-tasks via JQL: `"Epic Link" = <EPIC-KEY>` and recursively for sub-tasks.
+
+### Phase 2 — Extract atomic PRD items
+
+Walk the PRD content and produce a list of **atomic items** — testable, ticketable units of work. Each item gets a stable identifier so the matrix is auditable.
+
+The item types to extract:
+
+| Type | Where it appears in the PRD | Example identifier |
+|------|----------------------------|--------------------|
+| `goal` | `## Goals` section bullets | `goal:1`, `goal:2`, ... |
+| `non-goal` | `## Non-goals` (for scope-creep detection) | `non-goal:1` |
+| `user-story` | Per-Epic page, "User Story" sub-headings | `epic-1.story-1.1` |
+| `functional-req` | "Functional Requirements" sub-section | `epic-1.story-1.1.fr-1` |
+| `non-functional-req` | "Non-functional Requirements" sub-section | `epic-1.story-1.1.nfr-1` |
+| `acceptance-criterion` | Inline AC under a user story | `epic-1.story-1.1.ac-1` |
+| `important-note` | Bold "Important note:" callouts | `note:1` |
+| `mobile-spec` | Mobile-specific behavior callouts | `epic-1.story-1.1.mobile-1` |
+| `state` | Empty / error / loading state notes | `epic-2.story-2.1.state:empty` |
+| `permission` | Role-scoped permission notes | `epic-2.story-2.1.perm:admin` |
+| `decision` | Confirmed decisions in comments (e.g. "Engineering: ...") | `comment:42` |
+
+**Items NOT to extract** (these are not coverage gaps if missing):
+- Open Questions / `[Needs validation]` items — these are PRD-side blockers, not ticket scope.
+- Original concept thesis or annex/historical content — context, not requirements.
+- "Out of scope" items in the PRD — explicitly excluded by product.
+
+For each extracted item, capture: `{ id, type, source (PRD section / line), text (concise summary), keywords (3-5 terms for matching) }`.
+
+### Phase 3 — Map items to tickets
+
+For each created ticket (epic + each story + each sub-task), capture: `{ key, summary, description, acceptance_criteria, scope_signals (keywords from summary + AC) }`.
+
+Build a coverage matrix:
+
+```text
+PRD item id  →  [ticket keys that cover it]
+```
+
+Matching rules (in priority order):
+
+1. **Direct quote / strong keyword overlap**: the ticket's summary or AC explicitly names the PRD item's keywords. High confidence.
+2. **Domain match**: PRD item describes a UI affordance ("Tasks widget") and a ticket scopes that affordance (`[CU-2.1] Tasks widget — empty state`). Medium-high confidence.
+3. **Scope inheritance**: PRD item is a sub-detail of a parent (e.g. an AC under a user story); the ticket covers the parent user story. Medium confidence — flag for review if no more specific ticket exists.
+4. **Cross-ticket coverage**: PRD item spans multiple tickets (e.g. a permission rule that applies to several widgets). Each contributing ticket is recorded.
+
+Items with **zero** matching tickets are coverage gaps.
+
+### Phase 4 — Detect scope creep (informational)
+
+For each created ticket, identify any tickets whose scope_signals do NOT trace back to a PRD item, AND are not justifiable as standard infrastructure tasks (e.g. `X.0 Setup` stories for data model / migrations are typically infrastructure scaffolding, not scope creep).
+
+Scope creep is informational, not blocking — but worth surfacing because it usually indicates the agent invented work.
+
+### Phase 5 — Determine verdict
+
+| Condition | Verdict |
+|-----------|---------|
+| All extracted PRD items have ≥1 matching ticket; no scope creep | `COMPLETE` |
+| All extracted PRD items have ≥1 matching ticket; one or more scope-creep tickets | `COMPLETE_WITH_SCOPE_CREEP` |
+| One or more PRD items have zero matching tickets | `GAPS_FOUND` |
+| The created-tickets list is empty or unfetchable | `NO_TICKETS_FOUND` |
+
+`GAPS_FOUND` is the only verdict that should gate the PRD's `Status`. Scope creep is advisory — surface it, but do not block.
+
+### Phase 6 — Emit report
+
+Output a single fenced text block. Callers parse it; do not add free-form prose around it.
+
+```text
+## prd-ticket-coverage: <PRD title>
+
+PRD page: <URL>
+Tickets audited: <epic-key> + <story-count> stories + <subtask-count> sub-tasks
+Atomic PRD items extracted: <n>
+
+### Coverage matrix
+| PRD item | Tickets |
+|----------|---------|
+| <id> (<type>) — <text> | <ticket-key>, <ticket-key> |
+| <id> (<type>) — <text> | <ticket-key> |
+| <id> (<type>) — <text> | **(none)** |
+| ... | ... |
+
+### Gaps  (PRD items with zero ticket coverage — blocks Ticketed status)
+- <item-id> (<type>) — <text>
+  - *Source:* <PRD section reference>
+  - *Suggested fix:* <add a ticket scoped to X / extend ticket Y to cover this / clarify whether this is in scope>
+
+### Scope creep  (tickets without PRD trace — informational, does not block)
+- <ticket-key> — <summary>
+  - *Why flagged:* <reason — e.g. "no matching item in PRD; not an infra task">
+
+### Verdict: COMPLETE | COMPLETE_WITH_SCOPE_CREEP | GAPS_FOUND | NO_TICKETS_FOUND
+### Gap count: <n>
+### Scope-creep count: <n>
+```
+
+## Rules
+
+- Read-only — never write to JIRA, never write to Notion (callers do that based on the verdict).
+- Never silently drop a PRD item from extraction. If an item is ambiguous about whether it's scope, include it in extraction with type `ambiguous` and let the matching phase resolve it. The point of the audit is to catch silent drops; the audit can't have its own.
+- Be explicit about confidence in matches — the matrix is for humans to skim; vague matches help no one. If a match is rule-3 ("scope inheritance"), say so.
+- Scope creep is INFORMATIONAL. It is normal for an agent to add infra tickets (`X.0 Setup`) the PRD doesn't explicitly enumerate. Only flag scope creep when the ticket genuinely doesn't trace to PRD content AND isn't standard scaffolding.
+- The `GAPS_FOUND` verdict is the gate. The caller (e.g. `notion-prd-intake`) uses it to decide whether to revert `Status` from `Ticketed` to `Blocked`.

package/plugins/lisa/skills/product-walkthrough/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: product-walkthrough
+description: "Methodology for evaluating the live product via a real browser (Playwright MCP) when planning work or evaluating a PRD. Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change — this skill grounds the analysis in what actually exists today. Invoke this skill from notion-to-jira (Phase 2b live-product walkthrough), jira-create, and any PRD intake flow whose work touches existing user-facing surfaces."
+allowed-tools: ["Skill", "Bash", "Read", "mcp__plugin_playwright_playwright__browser_navigate", "mcp__plugin_playwright_playwright__browser_snapshot", "mcp__plugin_playwright_playwright__browser_take_screenshot", "mcp__plugin_playwright_playwright__browser_click", "mcp__plugin_playwright_playwright__browser_type", "mcp__plugin_playwright_playwright__browser_select_option", "mcp__plugin_playwright_playwright__browser_fill_form", "mcp__plugin_playwright_playwright__browser_press_key", "mcp__plugin_playwright_playwright__browser_hover", "mcp__plugin_playwright_playwright__browser_navigate_back", "mcp__plugin_playwright_playwright__browser_resize", "mcp__plugin_playwright_playwright__browser_tabs", "mcp__plugin_playwright_playwright__browser_console_messages", "mcp__plugin_playwright_playwright__browser_network_requests", "mcp__plugin_playwright_playwright__browser_wait_for", "mcp__plugin_playwright_playwright__browser_close"]
+---
+
+# Live Product Walkthrough
+
+Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change. This skill defines how to use a real browser (via Playwright MCP) to evaluate the live product *before* planning tickets, so the work is grounded in what actually exists today.
+
+## When to invoke
+
+Always run a walkthrough when the work touches user-facing surfaces:
+
+- The PRD describes a change to an existing screen, flow, or interaction
+- The PRD adds something *next to* existing functionality (entry points, navigation, related screens)
+- A mock or prototype implies a re-style or re-flow of something currently shipped
+- The change is a "bug" framed as a fix to current behavior — you must see the current behavior before reasoning about the fix
+
+Skip when the work is purely backend with no user-visible surface, type-only, doc-only, or affects a screen that does not yet exist in production / dev.
+
+## Configuration
+
+Required inputs (ask if not set):
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `E2E_BASE_URL` | Frontend base URL to walk through | `https://dev.example.io/` |
+| Sign-in account | Test user to sign in as for the affected flows | from PRD config / 1Password / env |
+| Sign-in credentials | How to obtain (1Password item, env vars) | `E2E_TEST_PHONE`, `E2E_TEST_OTP` |
+
+Walk through `dev` (or the env named in the PRD) — never `prod` for exploratory walkthroughs unless explicitly asked.
+
+## Process
+
+### 1. Plan the walkthrough
+
+Before opening the browser, list the surfaces the change will touch:
+
+- Which screens/routes are involved (current and new)?
+- Which user roles need to be exercised (admin / customer / etc.)?
+- Which states matter (signed-out, signed-in, empty, populated, error, loading)?
+- Which viewports matter (desktop always; mobile when responsive; tablet rarely)?
+
+Write this list down. If you can't, the PRD is too vague — note this as a coverage smell and surface it as an Open Question on the resulting ticket.
+
+### 2. Open the browser and sign in
+
+1. `browser_navigate` to `E2E_BASE_URL`.
+2. `browser_resize` to the primary viewport (default desktop 1512×768).
+3. Sign in via the test account. Use `browser_fill_form` and `browser_click`. Capture the post-login screen with `browser_snapshot` or `browser_take_screenshot`.
+
+### 3. Walk the affected surfaces
+
+For each surface from step 1:
+
+1. Navigate to it. Capture a `browser_snapshot` (accessibility tree — better for reasoning) and a `browser_take_screenshot` (visual evidence).
+2. Exercise the relevant interactions. Capture state transitions.
+3. Capture each state that matters (empty, populated, error, loading) — explicitly trigger them where possible.
+4. For responsive changes, `browser_resize` to the secondary viewport (mobile 375×812) and re-capture.
+5. `browser_console_messages` and `browser_network_requests` after each interaction — surface any errors, 4xx/5xx, or unexpected calls.
+
+### 4. Record findings
+
+For every walkthrough, record:
+
+- **What exists today**: a short prose description of the current flow, the components in use (if you can identify them from the DOM via `browser_snapshot`), and the states observed.
+- **What the PRD changes**: explicit delta — added screens, removed screens, modified components, new states, removed states.
+- **Existing-component reuse candidates**: components in the current product that could absorb the new behavior. The PRD-vs-current-product comparison drives which existing components a developer should reuse instead of building new (see `jira-source-artifacts` §7).
+- **Design-vs-current-product divergence**: places where the mock/prototype materially diverges from what's shipped. Each divergence is a discussion item, not an automatic "rebuild from scratch" — see `jira-source-artifacts` §3 (mocks define visual intent, not implementation shortcut).
+- **Coverage smells**: states the PRD doesn't address that exist today (e.g., the mock shows the empty state but ignores the populated state that has 90% of users).
+- **Behavioral surprises**: anything that doesn't match the PRD's assumptions about current behavior — these are usually the most valuable findings, because they invalidate parts of the PRD.
+
+### 5. Attach evidence to the originating context
+
+Capture screenshots/snapshots in a way that the originating ticket / Notion comment / PRD review can reference them.
+
+- For **PRD intake**: include a "Current Product" comment on the Notion PRD with the findings prose and inline screenshots of the current state alongside each affected screen mentioned in the PRD.
+- For **ticket creation**: include the findings under `## Current Product` in the ticket description (Story or Epic). Reference the screenshots as remote links if hosted, or inline them as attachments.
+- For **change-impact analysis**: produce a short report; the consuming skill decides where it lands.
+
+### 6. Close the browser
+
+`browser_close` when done. Walkthroughs are short, focused, and one-shot — do not leave a session open across phases.
+
+## Findings format
+
+Use this structure when emitting walkthrough findings, so consuming skills can splice them into tickets / comments unchanged. The `## Current Product` heading matches what `jira-write-ticket` Phase 4e expects to inherit — keep the heading exact.
+
+```text
+## Current Product
+
+**Environment**: <E2E_BASE_URL> as <account/role>
+**Viewports exercised**: Desktop 1512×768, Mobile 375×812
+
+### Surfaces walked
+1. <route> — <one-line current behavior>
+2. <route> — <one-line current behavior>
+
+### What exists today
+<2-4 sentence prose summary of the current flow and components in use>
+
+### Delta vs. PRD
+- ADDED: <new surface/state from PRD>
+- MODIFIED: <existing surface, with the change>
+- REMOVED: <existing surface PRD removes>
+- UNCHANGED-BUT-IMPACTED: <existing surface PRD doesn't mention but will be affected>
+
+### Existing-component reuse candidates
+- <component or screen> — could absorb <new behavior>
+
+### Design-vs-current-product divergence
+- <mock or prototype reference> diverges from <current screen> in: <specific dimension>
+- Recommendation: <reuse / new build / discussion>
+
+### Coverage smells & behavioral surprises
+- <smell or surprise>
+
+### Evidence
+- <list of screenshots/snapshots, with captions>
+```
+
+## Rules
+
+- Walk before you write. If the work touches existing user-facing surfaces and the walkthrough wasn't done, the resulting ticket is missing context — don't ship it.
+- Never walk `prod` for exploratory analysis. `dev` (or the env named in the PRD) only.
+- Treat console errors and unexpected network calls as findings — they often reveal undocumented behavior the PRD assumes is fine.
+- Findings drive `## Open Questions` on tickets, not silent assumptions. If the current product contradicts the PRD, surface it as a BLOCKER.
+- This skill captures observations; it does not edit JIRA or the PRD. Consuming skills decide where findings land (ticket description, Notion comment, validator input).

package/plugins/lisa/skills/ticket-triage/SKILL.md

@@ -10,6 +10,22 @@ Perform analytical triage on the JIRA ticket. The caller MUST have run `jira-rea
 
 Repository name for scoped labels and comment headers: determine via `basename $(git rev-parse --show-toplevel)`.
 
+## Phase 0 -- Pre-flight Description Gate
+
+Before any analytical work, confirm the ticket carries the content an implementer needs to start. The caller should already have run `jira-verify`; this phase consumes its output. If `jira-verify` returned `FAIL` for any of the following, emit `BLOCKED` immediately with the missing-requirements list and skip to Phase 6:
+
+- Epic parent missing (non-bug, non-epic)
+- Description quality failures (no Gherkin acceptance criteria, missing audience sections)
+- Validation Journey missing on a runtime-behavior ticket
+- Target backend environment missing on a runtime-behavior ticket
+- Sign-in credentials missing on a ticket that touches authenticated surfaces
+- Single-repo scope violated (Bug / Task / Sub-task spanning repos)
+- Relationship discovery missing (no links AND no documented git+JQL search)
+
+The caller (jira-agent) is responsible for transitioning the ticket to `Blocked`, reassigning to the **Reporter**, and posting a comment listing the missing requirements. This skill only emits the verdict and the missing-requirements list.
+
+If `jira-verify` returned `PASS` for all the above, proceed to Phase 1.
+
 ## Phase 1 -- Relevance Check
 
 Search the local codebase using Glob and Grep for code related to the ticket's subject matter:
@@ -123,7 +139,7 @@ Every verification method must be specific enough that an automated agent could
 Evaluate the findings and produce exactly one verdict:
 
 - **`NOT_RELEVANT`** -- No relevant code was found in this repository (Phase 1). The caller should add the triage label and skip implementation in this repo.
-- **`BLOCKED`** -- Blocking conditions were found in Phase 1.5 (open blockers, duplicate-of-open) and/or ambiguities were found in Phase 3. Work MUST NOT proceed until resolved by a human. The caller should post findings, add the triage label, and STOP.
+- **`BLOCKED`** -- Blocking conditions were found in Phase 0 (missing required description content), Phase 1.5 (open blockers, duplicate-of-open), and/or Phase 3 (ambiguities). Work MUST NOT proceed until resolved by a human. When the block is from Phase 0, the caller (jira-agent) MUST transition the ticket to `Blocked` and reassign to the Reporter — not just leave it in place. For Phase 1.5 / Phase 3 blocks, post findings, add the triage label, and STOP.
 - **`PASSED_WITH_FINDINGS`** -- No ambiguities, but edge cases or verification findings were identified. Work can proceed. The caller should post findings and add the triage label.
 - **`PASSED`** -- No ambiguities, edge cases, or verification gaps found. Work can proceed. The caller should add the triage label.
 
@@ -159,4 +175,5 @@ Structure all output with clear section headers so the caller can parse and post
 The caller is responsible for:
 1. Posting the findings as comments on the ticket (using whatever Jira mechanism is available)
 2. Adding the `claude-triaged-{repo}` label to the ticket
-3. If `BLOCKED`: stopping all work and reporting the ambiguities to the human
+3. If `BLOCKED` due to Phase 0 (missing required description content): transitioning the ticket to `Blocked`, reassigning to the **Reporter**, posting a comment listing the missing requirements, and stopping all work.
+4. If `BLOCKED` due to Phase 1.5 (open blockers, duplicate-of-open) or Phase 3 (ambiguities): stopping all work and reporting to the human; do NOT auto-transition status in these cases.