@codyswann/lisa 1.95.0 → 2.0.0

package/plugins/src/base/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.

package/plugins/src/base/skills/jira-verify/SKILL.md

@@ -1,104 +1,28 @@
 ---
 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 checks epic parent relationships and validates description completeness for coding assistants, developers, and stakeholders.
-allowed-tools: ["mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getAccessibleAtlassianResources"]
+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", "mcp__atlassian__getJiraIssue", "mcp__atlassian__getAccessibleAtlassianResources"]
 ---
 
 # Verify JIRA Ticket: $ARGUMENTS
 
-Fetch ticket $ARGUMENTS and verify it meets organizational standards.
+Verify that the existing JIRA ticket `$ARGUMENTS` meets organizational standards. This skill is a thin post-write wrapper around `jira-validate-ticket`: it fetches the live ticket and asks `jira-validate-ticket` to run the gates against the fetched state.
 
-## Verification Checks
+This indirection exists so the gate definitions live in exactly one place (`jira-validate-ticket`). When the bar changes, change it there — `jira-verify`, `jira-write-ticket` (Phase 5.5 pre-write), and `notion-to-jira` (PRD dry-run) all pick it up.
 
-### 1. Epic Parent Relationship
+## Process
 
-**Rule**: Non-bug, non-epic tickets MUST have an epic parent
+1. Resolve cloud ID via `mcp__atlassian__getAccessibleAtlassianResources`.
+2. Fetch the ticket via `mcp__atlassian__getJiraIssue` for `$ARGUMENTS`. Pull issue type, summary, description, parent, links, labels, components, and any custom fields needed.
+3. Invoke `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.
 
-- If missing: Search filter 10089 (Epic Backlog) and suggest appropriate epics
+## Output
 
-### 2. Description Quality
+Pass through `jira-validate-ticket`'s structured output unchanged. Do not summarize or paraphrase — downstream callers (e.g. `jira-agent`'s pre-flight gate) parse the gate lines.
 
-Verify description adequately addresses:
+## Notes
 
-**Coding Assistants**: Acceptance criteria, requirements, constraints, I/O
-**Developers**: Technical context, integration points, testing, edge cases
-**Stakeholders**: Business value, user impact, success metrics, summary
-
-### 3. Validation Journey
-
-**Rule**: Tickets that change runtime behavior MUST include a Validation Journey section.
-
-Check by running:
-
-```bash
-python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID> 2>&1
-```
-
-- If the parser returns steps: PASS
-- If the parser fails with "No 'Validation Journey' section found": FAIL — recommend using `/jira-add-journey <TICKET_ID>` to add one
-
-This check is skipped for:
-- Documentation-only tickets
-- Config-only tickets (env vars, CI/CD, feature flags)
-- Type-definition-only tickets (no runtime effect)
-- Epic-level tickets (journeys belong on child stories/tasks)
-
-### 4. Target Backend Environment
-
-**Rule**: Tickets that change runtime behavior MUST name a target backend environment in the description.
-
-Look for an `h2. Target Backend Environment` section (or equivalent named callout) containing one of `dev`, `staging`, or `prod`. The check is skipped for the same exclusions as the Validation Journey (doc-only, config-only, type-only, Epic).
-
-- If present and valid: PASS
-- If missing or unparseable: FAIL — recommend adding the section. QA/product report against a deployed env; the implementer needs to know which backend to point local at before CI/CD.
-
-### 5. Sign-in Credentials (Conditional)
-
-**Rule**: If the ticket touches an authenticated surface, the description MUST name the account/role to sign in as and where to get credentials.
-
-A surface is "authenticated" if any of these signals are present in the description, acceptance criteria, or Validation Journey:
-- Verbs like "log in", "sign in", "as a {role} user", "authenticated"
-- Routes/screens that require auth in this product
-- Roles named (admin, customer, partner, etc.)
-
-If those signals are present, look for an `h2. Sign-in Required` section naming an account or credential source.
-
-- If signals absent: PASS (sign-in not required)
-- If signals present and section present: PASS
-- If signals present and section missing: FAIL — recommend adding it. Implementers must not have to guess which account to use.
-
-### 6. Single-Repo Scope (Bug / Task / Sub-task)
-
-**Rule**: Bug, Task, and Sub-task tickets MUST cover one repo. Epic, Spike, and Story may span multiple repos.
-
-Check by inspecting the description's `h2. Repository` section (or equivalent) and any explicit cross-repo references in the description / acceptance criteria.
-
-- Bug / Task / Sub-task that names exactly one repo: PASS
-- Bug / Task / Sub-task that names multiple repos OR has acceptance criteria spanning repos: FAIL — recommend splitting into per-repo tickets under a parent Story/Epic.
-- Other types: skipped.
-
-### 7. Relationship Discovery
-
-**Rule**: Every ticket MUST have either at least one issue link OR a documented relationship search showing none was found.
-
-- If the ticket has any issue link (`blocks`, `is blocked by`, `relates to`, `duplicates`, `clones`): PASS
-- If no links but the description (or a comment) contains a `## Relationship Search` block listing the git and JQL queries that were run with their outcomes: PASS
-- If no links and no documented search: FAIL — recommend running `/jira-write-ticket` (or its discovery phase) to capture the search.
-
-## Execute Verification
-
-Retrieve ticket details, run all checks, and produce a single output block. For each FAIL include the specific remediation. The caller (typically `jira-agent`) uses the FAIL list to decide whether to gate work — see the agent's pre-flight gate.
-
-```text
-## jira-verify: <TICKET-KEY>
-- Epic parent: PASS | FAIL — <reason>
-- Description quality: PASS | FAIL — <reason>
-- Validation Journey: PASS | FAIL | N/A — <reason>
-- Target backend environment: PASS | FAIL | N/A — <reason>
-- Sign-in credentials: PASS | FAIL | N/A — <reason>
-- Single-repo scope: PASS | FAIL | N/A — <reason>
-- Relationship discovery: PASS | FAIL — <reason>
-
-## Verdict: PASS | FAIL
-## Missing requirements: [list of FAILed checks, or "none"]
-```
+- 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 `jira-validate-ticket` so this skill no longer shells out to it.

package/plugins/src/base/skills/jira-write-ticket/SKILL.md

@@ -170,28 +170,19 @@ Identify and attach:
 - Confluence pages (design docs, RFCs, runbooks)
 - Dashboards (Grafana, Datadog, Sentry issue)
 - Incident tickets (PagerDuty, Statuspage)
-- **Source artifacts from the originating PRD / parent epic**: Figma files, Lovable prototypes, Loom walkthroughs, design mockups, example payloads, Google Docs/Slides, collaborative whiteboards. If this ticket has a parent epic, enumerate the epic's remote links and inherit the ones whose domain matches this ticket's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit generic `reference` links). Never assume a developer will walk up to the epic to find design context — attach it here.
-
-Domain disambiguation (applied on inheritance):
-- Figma URL with `/proto/` in path or `starting-point-node-id=` in query → `ux-flow`; otherwise `ui-design`.
-- Lovable output → always `ux-flow`; its code/styling is not authoritative.
-- Loom / annotated screenshot → `ux-flow`.
-- Bare screenshot → `ui-design`.
+- **Source artifacts from the originating PRD / parent epic**: classify and inherit per the rules in `jira-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). The short version: enumerate the parent epic's remote links and inherit the ones whose domain matches this ticket's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`). Never assume a developer will walk up to the epic to find design context — attach it here.
 
 If the ticket was generated from a PRD (by `notion-to-jira` or similar) and the parent epic has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
 
 ### 4d. Source Precedence (must appear on the ticket)
 
-When a ticket carries both design artifacts and a description, different sources are authoritative for different questions. Record this precedence explicitly in the ticket description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts:
+Source precedence rules and cross-axis conflict handling are defined in `jira-source-artifacts` §3 and §4. When a ticket carries both design artifacts and a description, record the precedence explicitly in the ticket description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts. Cross-axis conflicts go under `## Open Questions` as BLOCKER items.
 
-- **Business rules** (required fields, validation, permissions, data constraints, edge cases) → the **description / PRD body** wins.
-- **Visual treatment** (layout, spacing, typography, color, iconography) → **mocks (`ui-design`)** win.
-- **Flow and interaction** (navigation, transitions, state changes, timing, empty/error/loading states) → **prototypes (`ux-flow`)** win.
-- **API / data shape** → **`data` artifacts** win.
+For UI-touching tickets, include the existing-component reuse expectation per `jira-source-artifacts` §7.
 
-Cross-axis conflicts (mock shows a field the PRD doesn't mention; prototype shows a flow the PRD contradicts; two Figma links disagree) must be raised as BLOCKER items in an `## Open Questions` section on the ticket — never silently reconciled.
+### 4e. Live Product Walkthrough Findings (UI-touching tickets)
 
-For UI-touching tickets, additionally include the reuse expectation: "Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling; raise design-vs-code divergence as a discussion item here rather than pixel-matching from scratch."
+If the ticket modifies an existing user-facing surface, a `product-walkthrough` should already have been run upstream (by `notion-to-jira` Phase 2b or `jira-create`). Inherit its findings under a `## Current Product` subsection in the ticket description so the implementer sees what's shipped today before changing it. If the upstream skill skipped the walkthrough but this ticket clearly modifies an existing surface, invoke `product-walkthrough` here before proceeding.
 
 Use Jira's web UI or `mcp__atlassian__editJiraIssue` to set the `Development` field / remote links where supported.
 
@@ -207,6 +198,19 @@ Before create/update, verify each field is populated where applicable:
 - Sprint: only if actively sprinting this work
 - Assignee: leave unset if unknown rather than auto-assigning
 
+## Phase 5.5 — Validate (Pre-write Gate)
+
+Before any write, invoke `jira-validate-ticket` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `jira-validate-ticket` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
+
+The validator is the **single source of truth** for what makes a valid ticket. The same gates are used by `notion-to-jira` dry-run, by `jira-verify` post-write, and here. Do not re-implement gate logic in this skill — if a gate needs to change, change `jira-validate-ticket` so every caller benefits.
+
+If the validator reports `FAIL`:
+- Surface the failure list and the per-gate remediation to the user.
+- Do NOT proceed to Phase 6. Fix the spec (or stop and ask the human) and re-run validation.
+- Never call `mcp__atlassian__createJiraIssue` or `mcp__atlassian__editJiraIssue` while the validator's verdict is FAIL.
+
+If the validator reports `PASS`, continue to Phase 6.
+
 ## Phase 6 — Create or Update
 
 ### CREATE
@@ -225,7 +229,7 @@ Before create/update, verify each field is populated where applicable:
 
 ## Phase 7 — Verify
 
-Call the `jira-verify` skill on the resulting ticket. If it reports failures, fix them before returning. Do not report success on a ticket that fails verify.
+Call the `jira-verify` skill on the resulting ticket. `jira-verify` fetches the live ticket and runs `jira-validate-ticket` against it — same gates as Phase 5.5, but applied to what JIRA actually stored (catches anything dropped or reformatted on write). If it reports failures, fix them before returning. Do not report success on a ticket that fails verify.
 
 ## Phase 8 — Announce
 
@@ -246,3 +250,4 @@ Skip this step only on UPDATE when no material change was made.
 - Never invent custom field values. If the project requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
 - All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `jira-create`) should delegate here rather than calling the MCP write tools directly.
+- The gate logic (what makes a valid ticket) lives in `jira-validate-ticket`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `jira-verify` post-write). When a gate needs to change, change it in `jira-validate-ticket` — every caller (write path, dry-run path, post-write verify) picks it up automatically.

package/plugins/src/base/skills/notion-prd-intake/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: notion-prd-intake
+description: "Scans a Notion PRD database for pages with Status=Ready and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and Status=Ticketed; PRDs that fail get clarifying-question comments and Status=Blocked. The skill is the runtime for the Ready → In Review → Blocked|Ticketed lifecycle. Composes existing skills (notion-to-jira, jira-validate-ticket, jira-source-artifacts, product-walkthrough); does not reimplement their logic."
+allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-search", "mcp__claude_ai_Notion__notion-update-page", "mcp__claude_ai_Notion__notion-create-comment", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Notion PRD Intake: $ARGUMENTS
+
+`$ARGUMENTS` is a Notion database URL (or bare database ID) — for example:
+
+```text
+https://www.notion.so/geminisports/28fd00244d7d47c5866876f7de48c0fe?v=34eba63a2800815891a3000c643f0ea8
+```
+
+Run one intake cycle against that database. Each PRD with `Status = Ready` is claimed, validated, and routed to either `Blocked` (with clarifying comments) or `Ticketed` (with JIRA tickets created).
+
+## Lifecycle assumed
+
+The PRD database has a `Status` property whose value drives this skill:
+
+```text
+Draft → Ready → In Review → Blocked | Ticketed → Shipped
+        (product)  (us)      (us)                  (product)
+```
+
+This skill ONLY transitions `Ready → In Review`, then `In Review → Blocked` or `In Review → Ticketed`. Never touches `Draft` or `Shipped`.
+
+## Phases
+
+### Phase 1 — Resolve the database
+
+1. Parse `$ARGUMENTS`:
+   - Full URL: extract the database ID from the path segment (the 32-hex-char ID after the last `/`, before `?`). Strip dashes if present. Ignore the `?v=...` view ID — we query the data source directly.
+   - Bare ID: use as-is.
+2. Call `mcp__claude_ai_Notion__notion-fetch` on the database ID. Capture:
+   - The data source ID from `<data-source url="collection://...">` — needed for queries.
+   - Confirm the schema includes a `Status` property of type `select` (or `status`) with the expected option names (`Ready`, `In Review`, `Blocked`, `Ticketed` at minimum). If any are missing, stop and report — the database is misconfigured.
+3. Resolve Atlassian cloud ID via `mcp__atlassian__getAccessibleAtlassianResources` (downstream skills need it).
+
+### Phase 2 — Find Ready PRDs
+
+Query the data source for pages where `Status = Ready`. Use `mcp__claude_ai_Notion__notion-search` with `data_source_url: collection://<data-source-id>` and a query that scopes to that collection. The search supports semantic queries; for an exact-status filter, scan the returned page list and keep only those whose `Status` property equals `Ready` (re-fetch each page if the search results don't expose properties).
+
+If the result set is empty, stop and report `"No PRDs with Status=Ready. Nothing to do."` Exit cleanly — this is the common idle case for a scheduled run.
+
+### Phase 3 — Process each Ready PRD
+
+For each PRD page (process serially to keep status transitions auditable):
+
+#### 3a. Claim
+
+Set `Status = In Review` via `mcp__claude_ai_Notion__notion-update-page` with `command: update_properties`, `properties: { "Status": "In Review" }`. This is the idempotency lock — if a second cycle starts while this one is mid-flight, the second skip-filter (`Status = Ready`) won't see this PRD.
+
+If the update fails (permission error, race), log it and skip this PRD. Do not proceed to validation on a PRD you didn't successfully claim.
+
+#### 3b. Dry-run validation
+
+Invoke the `notion-to-jira` skill with `dry_run: true` and the PRD's URL. The skill returns a structured report containing:
+- The planned ticket hierarchy
+- Per-ticket validation verdicts and remediation
+- An overall PASS / FAIL verdict
+- A failure count
+
+This call also indirectly invokes `jira-source-artifacts` (artifact extraction + classification) and `product-walkthrough` (when the PRD touches existing user-facing surfaces). All gate logic lives in `jira-validate-ticket`, which `notion-to-jira` calls per ticket.
+
+#### 3c. Branch on the verdict
+
+**If `PASS`** (every planned ticket passed every applicable gate):
+
+1. Re-invoke `notion-to-jira` with `dry_run: false` to actually write the tickets. This re-runs Phases 1-5 and runs the preservation gate (Phase 5.5).
+2. Capture the created ticket keys from the skill's output.
+3. Post a Notion comment on the PRD via `mcp__claude_ai_Notion__notion-create-comment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Move Status to Shipped after the work is delivered."`
+4. Set `Status = Ticketed` via `notion-update-page`.
+5. **Run Phase 3e (coverage audit)** before considering this PRD done.
+
+#### 3e. Coverage audit (mandatory after Ticketed)
+
+Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* of created tickets covers the *whole* PRD. Silent drops happen — invoke the `prd-ticket-coverage` skill to catch them.
+
+1. Invoke `prd-ticket-coverage` with `<PRD URL> tickets=[<created ticket keys from step 2 above>]`.
+2. Read the verdict:
+
+   | Verdict | Action |
+   |---------|--------|
+   | `COMPLETE` | Done. Leave `Status = Ticketed`. Move to next PRD. |
+   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory Notion comment naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave `Status = Ticketed`. |
+   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a Notion comment naming the missing PRD item and where it appears in the PRD, with the suggested fix from the audit report. (b) Post one summary comment listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Transition `Status` from `Ticketed` back to `Blocked` via `notion-update-page`. |
+   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave `Status = Ticketed` with a comment flagging the audit failure for human review. |
+
+3. The created tickets remain in JIRA regardless of the verdict — they are valid in their own right (they passed `jira-validate-ticket`). The audit only tells us whether *more* are needed.
+
+The audit's report should be summarized in the cycle summary alongside the per-PRD outcome (e.g., `Ticketed (coverage: COMPLETE)` or `Blocked (coverage gaps: 3)`).
+
+**If `FAIL`** (one or more planned tickets failed one or more gates):
+
+1. Group the failures by planned ticket.
+2. For each failed ticket, post a Notion comment via `notion-create-comment` with this format:
+
+   ```text
+   **Blocker — planned ticket: <ticket-summary>**
+
+   The PRD as written can't produce a valid JIRA ticket for this scope. Specifically:
+
+   - **<gate-id> (<gate-name>)**: <reason>. *Fix:* <concrete remediation>.
+   - **<gate-id> (<gate-name>)**: <reason>. *Fix:* <concrete remediation>.
+
+   Once these are addressed in the PRD, set Status back to `Ready` and Claude will re-run intake.
+   ```
+
+3. Set `Status = Blocked` via `notion-update-page`.
+4. Do NOT write any JIRA tickets.
+
+Each comment must name the specific planned ticket and the specific gate — vague guidance is useless to product. The remediation field on the validator's report is already concrete; pass it through.
+
+#### 3d. Continue
+
+Move to the next Ready PRD. One PRD failing does not affect others.
+
+### Phase 4 — Summary report
+
+After processing every Ready PRD, emit a summary:
+
+```text
+## notion-prd-intake summary
+
+Database: <name> (<URL>)
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+PRDs processed: <n>
+- Ticketed: <n>
+  - <PRD title> → <epic-key> + <story-count> stories + <subtask-count> sub-tasks (coverage: COMPLETE | COMPLETE_WITH_SCOPE_CREEP)
+- Blocked: <n>
+  - <PRD title> → <gate-failure-count> gate failures (pre-write) OR <gap-count> coverage gaps (post-write)
+- Errors (claim failed, etc): <n>
+  - <PRD title> — <reason>
+
+Total JIRA tickets created: <n>
+Coverage audit summary: <n> COMPLETE / <n> COMPLETE_WITH_SCOPE_CREEP / <n> GAPS_FOUND
+```
+
+Print to the agent's output. Do not write this summary to Notion or JIRA — it's an operational record for the human.
+
+## Idempotency & safety
+
+- **Single-cycle scope**: this skill processes the Ready set as it exists at the start of Phase 2. New `Ready` PRDs added mid-cycle are picked up next run.
+- **No writes outside the lifecycle**: this skill only ever writes to JIRA via `notion-to-jira` (which delegates to `jira-write-ticket`), and only ever changes Notion `Status` to `In Review`, `Blocked`, or `Ticketed`. It never edits PRD content, never touches `Draft` or `Shipped`, never deletes pages.
+- **Claim-first ordering**: `Status = In Review` is set BEFORE validation runs, so a re-entrant call won't double-process.
+- **Failure isolation**: an exception processing one PRD must not stop the cycle. Catch, record under "Errors" in the summary, continue to the next PRD. The PRD that errored is left in `In Review` — the human investigates from there.
+
+## Configuration
+
+This skill reads project configuration from environment variables (or `$ARGUMENTS` overrides). If any required value is missing, ask the user before proceeding — never invent values.
+
+| Variable | Purpose |
+|----------|---------|
+| `JIRA_PROJECT` | JIRA project key for ticket creation (passed to `notion-to-jira`) |
+| `JIRA_SERVER` | Atlassian instance host |
+| `E2E_BASE_URL` | Frontend URL for `product-walkthrough` |
+| `E2E_TEST_PHONE` / `E2E_TEST_OTP` / `E2E_TEST_ORG` | Test user creds for walkthrough + verification plans |
+| `E2E_GRAPHQL_URL` | API URL for verification plans |
+
+## Rules
+
+- Never write to JIRA outside of `notion-to-jira` → `jira-write-ticket`. The validator's verdict gates progress; bypassing it produces broken tickets.
+- Never set Notion `Status` to a value this skill doesn't own (`In Review`, `Blocked`, `Ticketed`). Product owns `Draft`, `Ready`, `Shipped`.
+- Never edit the PRD's body. Communication with product happens only through Notion comments.
+- Never run more than one intake cycle concurrently against the same database. This skill assumes serial execution. (Scheduling is a separate concern; the runtime should not start a new cycle if a previous one is still in flight.)
+- If `notion-to-jira` returns errors (e.g. unreachable artifact, malformed PRD structure), treat them as gate failures: comment + Blocked. Don't silently fail.