@codyswann/lisa 2.2.0 → 2.4.0

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

@@ -0,0 +1,318 @@
+---
+name: confluence-to-jira
+description: >
+  Break down a Confluence PRD page into JIRA epics, stories, and sub-tasks. Use this skill whenever the
+  user shares a Confluence PRD URL and wants it converted into JIRA tickets, or asks to "break down
+  this Confluence spec", "create tickets from a Confluence page", "turn this Confluence doc into JIRA",
+  or similar. This skill mirrors `lisa:notion-to-jira` for projects whose PRDs live in Confluence —
+  the workflow, gates, dry-run mode, and validation rules are identical; only the source-of-truth tool
+  surface differs (Confluence MCP instead of Notion MCP).
+allowed-tools: ["Skill", "Bash", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluencePageDescendants", "mcp__atlassian__getConfluencePageFooterComments", "mcp__atlassian__getConfluencePageInlineComments", "mcp__atlassian__getConfluenceCommentChildren", "mcp__atlassian__searchConfluenceUsingCql", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__atlassian__getJiraIssueRemoteIssueLinks"]
+---
+
+# Confluence PRD to JIRA Breakdown
+
+Convert a Confluence 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.
+
+This skill is the Confluence counterpart of `lisa:notion-to-jira`. The two skills share the same
+phases, gates, dry-run contract, and per-ticket validation logic. Only the PRD-side fetch / comment
+tools differ. When changing workflow logic, change BOTH skills together so the two source vendors
+stay behaviorally identical.
+
+## 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 `lisa: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 `lisa: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. `lisa:confluence-prd-intake`) can decide whether to proceed.
+
+Dry-run output format is identical to `lisa:notion-to-jira`'s. Reuse the same fields, including
+`prd_anchor` and `prd_section`. The only difference: `prd_anchor` is the inline-comment anchor text
+that `createConfluenceInlineComment` accepts (typically the full selected substring; truncate if it
+exceeds the tool's max anchor length and emit `null` if no resolvable anchor exists).
+
+```text
+## confluence-to-jira dry-run: <PRD title>
+
+### Planned hierarchy
+- Epic: <summary>
+  prd_section: "<heading text from the PRD that produced this epic>"
+  prd_anchor: "<inline-comment anchor text>"   # null if no specific section
+  - Story 1.1: <summary>
+    prd_section: "<heading or user-story line>"
+    prd_anchor: "<anchor>"
+    - Sub-task [<repo>]: <summary>
+      prd_section: "<heading or AC bullet>"
+      prd_anchor: "<anchor>"
+    - ...
+  - Story 1.2: ...
+
+### Per-ticket validation
+- <ticket-id>: PASS | FAIL — <count> failures
+  prd_section: "<heading text>"
+  prd_anchor: "<anchor>"
+  failures:
+    - gate: <gate-id>
+      category: <category from validator>
+      product_relevant: <true|false>
+      what: <plain-language description from validator>
+      recommendation: <1–3 candidate resolutions from validator>
+
+### Verdict: PASS | FAIL
+### Total failures: <n>
+```
+
+The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJiraIssue`. It also never
+modifies the source Confluence page, never adds/removes labels, and never posts comments — that is the
+orchestrating skill's responsibility (`lisa:confluence-prd-intake`).
+
+## Hard Rule: All Writes Go Through `lisa:jira-write-ticket`
+
+**Every JIRA ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa: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.**
+
+`lisa: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 `lisa:jira-write-ticket` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. The Atlassian read tools (`getJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssueRemoteIssueLinks`, `getAccessibleAtlassianResources`, `getJiraProjectIssueTypesMetadata`, `getVisibleJiraProjects`, and the Confluence read endpoints listed in `allowed-tools` above) ARE allowed for context gathering and the Phase 5.5 preservation gate.
+
+## Input
+
+A Confluence PRD page URL or page ID. The PRD is expected to have:
+- A main page with context, problems, and child pages for each Epic
+- Epic child pages with User Stories and functional/non-functional requirements
+- Page comments (footer + inline) with engineering notes and product decisions
+
+URL parsing — Confluence URLs come in two common shapes:
+
+```text
+https://<host>/wiki/spaces/<SPACE>/pages/<PAGE-ID>/<slug>
+https://<host>/wiki/spaces/<SPACE>/pages/<PAGE-ID>
+```
+
+Extract `<PAGE-ID>` (the numeric segment after `/pages/`). If only a space URL is provided
+(`/wiki/spaces/<SPACE>` with no `/pages/...`), stop and report — single-PRD mode requires a specific
+page. The caller wanted `lisa:confluence-prd-intake` (batch mode).
+
+## Configuration
+
+This skill reads project-specific configuration from environment variables. If these are not set,
+ask the user for the values before proceeding.
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `JIRA_PROJECT` | JIRA project key for ticket creation | `SE` |
+| `JIRA_SERVER` | Atlassian instance URL (site host) | `mycompany.atlassian.net` |
+| `CONFLUENCE_HOST` | Confluence host (often same as `JIRA_SERVER`) | `mycompany.atlassian.net` |
+| `E2E_TEST_PHONE` | Test user phone number for verification plans | `0000000099` |
+| `E2E_TEST_OTP` | Test user OTP code | `555555` |
+| `E2E_TEST_ORG` | Test organization name | `Arsenal` |
+| `E2E_BASE_URL` | Frontend base URL for Playwright tests | `https://dev.example.io/` |
+| `E2E_GRAPHQL_URL` | GraphQL API URL for curl verification | `https://gql.dev.example.io/graphql` |
+
+If env vars are not available, ask the user to provide them explicitly before proceeding.
+Do not retrieve credentials from repository files or local agent settings.
+
+## Workflow
+
+### Phase 1: Fetch & Analyze the PRD
+
+1. **Resolve the Atlassian cloud ID** via `mcp__atlassian__getAccessibleAtlassianResources`. Confluence MCP calls require it.
+2. **Fetch the main PRD page** via `mcp__atlassian__getConfluencePage` with the page ID. Capture body, labels, and child page references.
+3. **Identify all Epic child pages** via `mcp__atlassian__getConfluencePageDescendants` (one level deep first; recurse if the PRD nests epics under a "Specs" parent).
+4. **Fetch all Epic pages** in parallel via `getConfluencePage`.
+5. **Fetch full comments** for the main page and every epic page in parallel:
+   - `mcp__atlassian__getConfluencePageFooterComments` — page-level threaded comments (equivalent to Notion's page-level discussions)
+   - `mcp__atlassian__getConfluencePageInlineComments` — block-anchored comments tied to specific text spans
+   - For any comment with replies, walk the tree via `mcp__atlassian__getConfluenceCommentChildren` until exhausted
+6. **Synthesize decisions and blockers** from the PRD content + all comments:
+   - Decisions already confirmed by the team (look for agreement in comment threads)
+   - Open questions that need product/engineering input
+   - Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
+   - Cross-PRD dependencies (references to other features or shared infrastructure)
+
+### Phase 1.5: Extract Source Artifacts
+
+PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, peer Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
+
+1. **Scan the PRD main page, all Epic child pages, and every fetched comment thread** for:
+   - URLs to design/prototype tools (Figma, FigJam, Figma Make, Lovable, Framer, Penpot)
+   - URLs to recording/walkthrough tools (Loom, YouTube, Vimeo, Descript)
+   - URLs to collaborative docs (Google Docs/Slides/Sheets, peer Confluence pages, Notion peer pages)
+   - URLs to code sandboxes (CodeSandbox, StackBlitz, Replit, GitHub permalinks/gists)
+   - URLs to diagramming tools (Miro, Mural, Excalidraw, Mermaid Live, draw.io, Lucid)
+   - URLs to data/observability tools (Grafana, Datadog, Sentry, Metabase, Looker)
+   - 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 and apply taxonomy rules** by invoking the `lisa: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.
+
+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. The `source_page` lets you trace each reference back to where it appeared in the PRD.
+
+4. **Surface coverage smells** as defined in `lisa:jira-source-artifacts` §5. Record any detected smells on the epic.
+
+### Phase 1.6: Source Precedence & Conflict Resolution
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa: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.
+
+The existing-component reuse expectation is defined in `lisa:jira-source-artifacts` §7. Encode it on every UI-touching story.
+
+### Phase 2: Codebase + Live Product Research
+
+Identical to `lisa:notion-to-jira` Phase 2. 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.
+
+**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.
+
+**2b. Live product walkthrough.** If the PRD touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill against `E2E_BASE_URL` using the test user from config.
+
+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 Confluence PRD as a **footer comment** (Confluence has no general "page-level discussion attached to a heading" — footer comments are the page-level equivalent), via `mcp__atlassian__createConfluenceFooterComment`. Title the comment "Current product walkthrough — `<route>`". Inherited onto the resulting epic / stories under a `## Current Product` subsection.
+
+### Phase 3: Create Epics
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:jira-write-ticket` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `lisa: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.
+
+For each PRD epic, **invoke the `lisa:jira-write-ticket` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
+
+- `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 Confluence 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. No filtering at the epic level.
+- `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
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:jira-write-ticket` in this phase. Instead, draft each story spec and validate it with `lisa: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
+- **One story per user story** from the PRD (numbered to match the PRD)
+
+**Story naming convention**: Prefix the summary with a short code derived from the PRD title (e.g., `[CU-1.1]` for "Contract Upload").
+
+For each story, **invoke `lisa:jira-write-ticket`** with:
+
+- `project_key`: from `JIRA_PROJECT` config
+- `issue_type`: `Story`
+- `epic_parent`: the Epic key captured in Phase 3 (mandatory)
+- `summary`: prefixed per the naming convention above
+- `description_body`: 3-audience description as in `lisa:notion-to-jira` Phase 4
+- `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below
+
+| 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 |
+
+Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
+
+### Phase 5: Create Sub-tasks
+
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:jira-write-ticket` for each sub-task — no agent may call `createJiraIssue` directly.**
+
+Each sub-task MUST:
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`
+2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
+
+Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task.
+
+### Phase 5.5: Artifact Preservation Gate (mandatory)
+
+Run the preservation gate defined in `lisa: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 `lisa:jira-source-artifacts`.
+
+To run the gate, this skill must:
+
+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 and either re-attach via `lisa:jira-write-ticket` (UPDATE mode) or stop and ask the human.
+4. If the gate passes: print the matrix compactly and proceed to Phase 6.
+
+This gate is not optional.
+
+### Phase 6: Report Results
+
+After all tickets are created, present a summary table to the user:
+- All Epics with keys and URLs
+- All Stories grouped by Epic
+- All Sub-tasks grouped by Story with repo tags
+- Repo distribution
+- **Artifact Preservation Matrix**
+- Blockers list with recommendations and alternatives
+- Cross-PRD dependencies
+
+## Handling Ambiguities and Blockers
+
+When you encounter something the PRD + comments + codebase can't resolve:
+
+1. **Don't guess** — mark the ticket with a BLOCKER section
+2. **Include your recommendation** with rationale
+3. **List 2-3 alternatives** so the user/product can choose
+4. **State what's needed to unblock**
+
+## Agent Prompt Template for Sub-task Creation
+
+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].
+
+CRITICAL: For each sub-task, invoke the `lisa:jira-write-ticket` skill via the Skill tool.
+Do NOT call `mcp__atlassian__createJiraIssue` directly. The `lisa: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 `lisa: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 — repo named in brackets in the summary
+2. Include the Empirical Verification Plan in the description
+3. Be created via `lisa:jira-write-ticket`, not via direct MCP calls
+
+If `lisa:jira-write-ticket` rejects a sub-task, 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]
+```
+
+## Cross-PRD Shared Infrastructure
+
+Track tickets that are shared across PRDs to avoid duplication. When a sub-task overlaps with an existing ticket, reference it instead of creating a duplicate. Search JIRA for existing tickets in the project before creating new ones for shared infrastructure.
+
+## Confluence-specific notes
+
+- **Page bodies** come back from `getConfluencePage` as either Atlassian Document Format (ADF / storage format) or rendered HTML depending on flags. Treat headings (`<h1>`–`<h3>`) as section markers for `prd_section`. For ADF, walk the document tree.
+- **Inline comment anchors**: `prd_anchor` is the inline-comment selection text (the exact substring `createConfluenceInlineComment` will match). If the section is too long for an inline anchor (Confluence has a practical upper bound on selection length), pick the first sentence of the section. If the section has no stable anchor (e.g., a generated table cell), set `prd_anchor: null` and the caller will fall back to a footer comment.
+- **Comment threading**: Confluence has separate footer and inline comment streams. When fetching comments in Phase 1, merge both into the analysis — they are equally authoritative for capturing decisions and engineering notes.

package/plugins/lisa/skills/intake/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: intake
-description: "Vendor-agnostic batch scanner for Status=Ready queues. Given a Notion PRD database URL → finds Ready PRDs and runs lisa:plan per item. Given a JIRA project key or JQL filter → finds Ready tickets and runs lisa:implement per item. Designed as the cron target for /schedule — one cycle per invocation, processes everything currently Ready, exits cleanly on empty. Symmetric counterpart to the single-item lisa:plan and lisa:implement skills."
-allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-search", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getJiraIssue"]
+description: "Vendor-agnostic batch scanner for Ready queues. Given a Notion PRD database URL → finds Ready PRDs and runs lisa:plan per item. Given a Confluence space or parent page URL → finds prd-ready PRDs and runs lisa:plan per item. Given a JIRA project key or JQL filter → finds Ready tickets and runs lisa:implement per item. Designed as the cron target for /schedule — one cycle per invocation, processes everything currently Ready, exits cleanly on empty. Symmetric counterpart to the single-item lisa:plan and lisa:implement skills."
+allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-search", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluenceSpaces", "mcp__atlassian__searchConfluenceUsingCql", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getJiraIssue"]
 ---
 
 # Intake: $ARGUMENTS
@@ -40,11 +40,21 @@ Detect the queue type from `$ARGUMENTS` and route:
 | If `$ARGUMENTS` is... | Queue type | Per-item dispatch |
 |------------------------|------------|---------------------|
 | A Notion **database** URL or database ID | PRD queue (Notion) | Invoke `lisa:notion-prd-intake` (which scans the DB for Status=Ready, claims each, runs `lisa:plan` per PRD via the dry-run validate → branch → write pipeline) |
+| A Confluence **space** URL or space key (e.g. `https://acme.atlassian.net/wiki/spaces/PRD` or `PRD`) | PRD queue (Confluence) | Invoke `lisa:confluence-prd-intake` (which CQL-queries the space for `label = "prd-ready"`, claims each by relabeling to `prd-in-review`, runs the dry-run validate → branch → write pipeline) |
+| A Confluence **parent page** URL or page ID (the page whose descendants are PRDs) | PRD queue (Confluence, narrowed) | Invoke `lisa:confluence-prd-intake` with the parent ID (CQL: `ancestor = <id> AND label = "prd-ready"`) |
 | A JIRA project key (e.g. `SE`) | Work queue (JIRA) | Invoke `lisa:jira-build-intake` (which scans the project for Status=Ready, claims each via In Progress, runs `lisa:implement` per ticket, transitions to On Dev on success) |
 | A full JQL filter (e.g. `project = SE AND component = "frontend"`) | Work queue (JIRA, narrowed) | Invoke `lisa:jira-build-intake` with the JQL |
 | A Linear / GitHub Issues queue | Not yet implemented | Stop and report — no `linear-tracker` or `github-tracker` adapter has been built. Don't fall back. |
 
-The single-item skills (`lisa:plan`, `lisa:implement`) and the per-vendor batch skills (`lisa:notion-prd-intake`, `lisa:jira-build-intake`) are internal — Intake is the public entry point. Developers schedule `/lisa:intake <queue>`; the rest is composition.
+Disambiguation rules:
+
+- A `notion.so` / `notion.site` URL → Notion queue.
+- An Atlassian Confluence URL containing `/wiki/spaces/<KEY>` with no `/pages/...` segment → Confluence space queue.
+- An Atlassian Confluence URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` → Confluence parent-page queue (the page is the parent whose descendants are PRDs). If the user actually meant "this single page is a PRD, plan it", route to `lisa:plan` instead — this skill is batch-only.
+- A bare alphanumeric token that matches the configured `JIRA_PROJECT` regex (uppercase letters / digits / hyphen, ≤10 chars) is treated as a JIRA project key by default. A token that does not match the regex is treated as a Confluence space key. The only time to stop and ask is when the token matches the JIRA_PROJECT regex AND is also a confirmed reachable Confluence space key (verified via Atlassian API) — in that specific overlap the user must disambiguate which queue to scan.
+- A string starting with `project = ` or containing JQL operators (`AND`, `OR`, `=`, `!=`, `~`, etc.) → JQL filter.
+
+The single-item skills (`lisa:plan`, `lisa:implement`) and the per-vendor batch skills (`lisa:notion-prd-intake`, `lisa:confluence-prd-intake`, `lisa:jira-build-intake`) are internal — Intake is the public entry point. Developers schedule `/lisa:intake <queue>`; the rest is composition.
 
 ## Cycle behavior
 
@@ -52,7 +62,8 @@ The single-item skills (`lisa:plan`, `lisa:implement`) and the per-vendor batch
 2. **Pre-flight check** — for JIRA, confirm `In Progress` and `On Dev` are reachable transitions before doing any per-ticket work. Stop with a clear error if the workflow is misconfigured.
 3. **Find Ready items** — query the queue. Empty → exit cleanly with `"No items with Status=Ready. Nothing to do."` This is the common idle case for a scheduled run.
 4. **Process each Ready item serially** (claim-first ordering for idempotency):
-   - Notion PRDs → `lisa:notion-prd-intake` handles per-item: claim, dry-run validate, branch to Blocked or Ticketed, coverage audit
+   - Notion PRDs → `lisa:notion-prd-intake` handles per-item: claim (Status=In Review), dry-run validate, branch to Blocked or Ticketed, coverage audit
+   - Confluence PRDs → `lisa:confluence-prd-intake` handles per-item: claim (relabel to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed`, coverage audit
    - JIRA tickets → `lisa:jira-build-intake` handles per-item: claim, dispatch to `lisa:jira-agent`, transition to On Dev on success
 5. **Failure isolation** — one item failing does not stop the cycle; record under "Errors" and continue.
 6. **Summary report** — per-item outcomes, total processed, total errors.
@@ -61,6 +72,7 @@ The single-item skills (`lisa:plan`, `lisa:implement`) and the per-vendor batch
 
 ```text
 /schedule "every 30 minutes" /lisa:intake https://www.notion.so/<workspace>/<database-id>
+/schedule "every 30 minutes" /lisa:intake https://acme.atlassian.net/wiki/spaces/PRD
 /schedule "every 30 minutes" /lisa:intake SE
 /schedule "every hour" /lisa:intake "project = SE AND component = 'frontend'"
 ```

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

@@ -66,6 +66,39 @@ If the caller passes only a ticket key, fetch the ticket via `mcp__atlassian__ge
 
 Gates are grouped into **Specification** (spec-only checks, no JIRA lookups) and **Feasibility** (requires JIRA lookups). The dry-run path may opt to run Specification gates only; the write path runs both.
 
+Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Categories drive how downstream callers (notably `lisa:notion-prd-intake`) translate failures into product-facing comments; `product_relevant=false` failures indicate internal data-quality problems (broken parent links, missing core fields) that the agent should fix itself rather than ask product to clarify.
+
+| Gate | Category | Product-relevant |
+|------|----------|------------------|
+| S1 Required core fields | `structural` | false |
+| S2 Summary format | `structural` | false |
+| S3 Description three audiences | `product-clarity` | true |
+| S4 Acceptance criteria in Gherkin | `acceptance-criteria` | true |
+| S5 Bug-specific content | `product-clarity` | true |
+| S6 Spike-specific content | `scope` | true |
+| S7 Epic parent declared | `structural` | false |
+| S8 Target Backend Environment | `technical` | false |
+| S9 Sign-in Required | `technical` | false |
+| S10 Single-repo scope | `scope` | true |
+| S11 Validation Journey | `acceptance-criteria` | true |
+| S12 Source Precedence | `design-ux` | true |
+| S13 Relationship Search | `dependency` | true |
+| F1 Issue type valid in project | `structural` | false |
+| F2 Epic parent exists and is an Epic | `structural` | false |
+| F3 Linked tickets exist | `structural` | false |
+| F4 Required custom fields populated | `structural` | false |
+
+Category values are drawn from this fixed set:
+
+- `product-clarity` — feature behavior or user intent unclear in the PRD
+- `acceptance-criteria` — pass/fail conditions missing or ambiguous
+- `design-ux` — visual or interaction spec missing
+- `scope` — boundary unclear, items overlap, split needed
+- `dependency` — blocked by another team / system / decision
+- `data` — data source / shape / volume unspecified
+- `technical` — engineering decision required (rare from PRD path; mostly internal)
+- `structural` — internal data-quality problem the agent must fix itself, not surface to product
+
 ### Specification Gates
 
 #### S1 — Required core fields
@@ -209,16 +242,32 @@ Output is a single fenced text block. Callers parse it; do not add free-form pro
 
 ### Verdict: PASS | FAIL
 ### Failures: <count>
-### Remediation
-- <gate-id>: <concrete fix the caller can apply or surface to the user>
-- <gate-id>: <concrete fix>
+### Failure details
+- gate: <gate-id>
+  category: <product-clarity|acceptance-criteria|design-ux|scope|dependency|data|technical|structural>
+  product_relevant: <true|false>
+  what: <plain-language description of what is missing or wrong, no gate-IDs, no JIRA terminology — written so a non-engineer product owner understands the issue>
+  recommendation: <1–3 concrete options the caller (or downstream product team) can pick from. Never "clarify this" — always a specific suggested resolution.>
+- gate: <gate-id>
+  category: ...
+  ...
 ```
 
 The verdict is `PASS` if and only if every applicable gate is `PASS`. Any `FAIL` makes the verdict `FAIL`. `N/A` does not affect the verdict.
 
+### Failure-detail fields
+
+- **gate**: the gate ID (`S1`–`S13`, `F1`–`F4`).
+- **category**: the gate's fixed category from the table above. Callers use this to label or filter comments — `product-clarity`, `acceptance-criteria`, `design-ux`, `scope`, `dependency`, `data`, `technical`, or `structural`.
+- **product_relevant**: matches the gate's table entry. `false` means the failure is an internal data-quality problem (e.g., the agent built a malformed spec, an issue type is invalid in the project) and the caller should fix it without bothering the product team. `true` means the PRD needs product input to resolve.
+- **what**: plain-language description of the issue. No gate IDs, no JIRA jargon, no engineering shorthand. A product owner reading this on a Notion comment should understand what is unclear and why.
+- **recommendation**: 1–3 concrete options the reader can pick from, not a generic "please clarify." If the answer is genuinely open-ended, list the most plausible candidate resolutions you considered, even if speculative.
+
 ## Rules
 
 - Never write to JIRA. 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.
+- The `what` and `recommendation` fields must be concrete and product-readable — the dry-run path turns each failure into a Notion comment, and the audience for those comments is the product team, not engineers. Vague guidance ("clarify this", "decide how to handle X") is useless; always give 1–3 candidate resolutions.
+- Never emit a category outside the fixed set. If a new gate doesn't fit, propose adding the category to the taxonomy in this skill rather than inventing one inline.
+- `product_relevant` is determined by the gate, not by the failure context. Do not flip it per-failure.

package/plugins/lisa/skills/notion-prd-intake/SKILL.md

@@ -101,7 +101,7 @@ Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* o
    |---------|--------|
    | `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`. |
+   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a Notion comment using the same product-facing template as Phase 3c.3 — block-anchored via `selection_with_ellipsis` when `prd_anchor` is non-null, page-level otherwise; category badge from the gap's `category` field; `What's unclear` and `Recommendation` from the audit report's `what` and `recommendation` fields. Apply the same forbidden-language rules from Phase 3c.5. (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 `lisa:jira-validate-ticket`). The audit only tells us whether *more* are needed.
@@ -110,24 +110,65 @@ The audit's report should be summarized in the cycle summary alongside the per-P
 
 **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:
+The audience for these comments is the **product team**, not engineers. They are not familiar with JIRA gate IDs, validator vocabulary, or skill internals. Follow the rules below strictly — the goal is for a non-engineer product owner to read a comment, understand what is unclear, and know what to do next.
 
-   ```text
-   **Blocker — planned ticket: <ticket-summary>**
+##### 3c.1 Partition failures
 
-   The PRD as written can't produce a valid JIRA ticket for this scope. Specifically:
+1. Drop every failure where `product_relevant = false`. Those are internal data-quality problems — the agent should fix its own spec rather than ask product to clarify a missing core field. Record the dropped failures under `Errors` in the cycle summary so engineers can see them; never surface them on the PRD.
+2. Group the remaining product-relevant failures by `prd_anchor` (the snippet from `notion-to-jira`'s dry-run report). Failures that share an anchor become one comment thread on that block. Failures with `prd_anchor: null` are batched into one page-level summary comment, since they have no source section to attach to.
 
-   - **<gate-id> (<gate-name>)**: <reason>. *Fix:* <concrete remediation>.
-   - **<gate-id> (<gate-name>)**: <reason>. *Fix:* <concrete remediation>.
+##### 3c.2 Render each comment
 
-   Once these are addressed in the PRD, set Status back to `Ready` and Claude will re-run intake.
-   ```
+For each anchored group, post via `mcp__claude_ai_Notion__notion-create-comment` with:
+- `page_id`: the PRD page ID
+- `selection_with_ellipsis`: the `prd_anchor` value (e.g. `"# User taps Fol...esume action"`)
+- `rich_text`: the body, formatted using the template below
 
-3. Set `Status = Blocked` via `notion-update-page`.
-4. Do NOT write any JIRA tickets.
+For the unanchored group, post a single page-level comment (omit `selection_with_ellipsis`) using the same template, prefixed with `Issues without a specific section anchor:` and one block per failure.
 
-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.
+##### 3c.3 Comment template
+
+Each comment body MUST contain these four parts, in this order, no exceptions:
+
+```text
+[<Category badge>] <prd_section heading text>
+
+**What's unclear:** <validator's `what` field, verbatim — already product-readable>
+
+**Recommendation:** <validator's `recommendation` field, verbatim — must contain 1–3 concrete options, never a generic "please clarify">
+
+**Action:** Update this section in the PRD, then set Status back to `Ready` and Claude will re-run intake.
+```
+
+If multiple failures share an anchor, render each as its own `**What's unclear:** ... **Recommendation:** ...` block within the same comment, separated by horizontal lines (`---`). Keep the single `[Category badge]` heading at the top using the most-severe / most-blocking category from the group.
+
+##### 3c.4 Category badges
+
+Use these exact badge labels — they are the validator's category values translated for product readers:
+
+| Validator category | Badge label |
+|---------------------|-------------|
+| `product-clarity` | `[Product clarity]` |
+| `acceptance-criteria` | `[Acceptance criteria]` |
+| `design-ux` | `[Design / UX]` |
+| `scope` | `[Scope]` |
+| `dependency` | `[Dependency]` |
+| `data` | `[Data]` |
+| `technical` | `[Technical]` |
+
+`structural` failures must never reach this step (filtered in 3c.1). If you see one here, treat it as an Error and surface internally.
+
+##### 3c.5 Forbidden in product comments
+
+- Gate IDs (`S4`, `F2`, etc.). Never appear in a comment body.
+- JIRA terminology that has no product meaning (e.g. "Gherkin", "epic parent", "issue link", "validation journey", "sub-task hierarchy"). If the validator's `what` field uses one of these terms, paraphrase before posting; do not pass through verbatim.
+- Internal skill names (`lisa:jira-validate-ticket`, `notion-to-jira`).
+- Engineering shorthand (`AC`, `OOS`, `repo`, `env var`).
+- "Clarify this" / "Please specify" without candidate resolutions. The validator is required to provide candidates; if `recommendation` is empty or vague, treat the failure as an Error and surface internally rather than posting a useless comment.
+
+##### 3c.6 Status transition
+
+After all comments are posted (anchored groups + the optional page-level summary), set `Status = Blocked` via `notion-update-page`. Do NOT write any JIRA tickets.
 
 #### 3d. Continue
 
@@ -182,5 +223,7 @@ This skill reads project configuration from environment variables (or `$ARGUMENT
 - Never write to JIRA outside of `lisa:notion-to-jira` → `lisa: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 post a single page-level dump of all gate failures. One comment per `prd_anchor` group (or one page-level summary for unanchored failures only). The audience is product, not engineers — comments must be block-anchored, categorized, plain-language, and contain a concrete recommendation. See Phase 3c.3 for the required template and Phase 3c.5 for forbidden language.
+- Never include a gate ID, internal skill name, or engineering shorthand in a Notion comment body. If the validator's `what` or `recommendation` field uses one, paraphrase before posting.
 - 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 `lisa:notion-to-jira` returns errors (e.g. unreachable artifact, malformed PRD structure), treat them as gate failures: comment + Blocked. Don't silently fail.

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

@@ -28,19 +28,36 @@ Dry-run output format:
 
 ### Planned hierarchy
 - Epic: <summary>
+  prd_section: "<heading text from the PRD that produced this epic>"
+  prd_anchor: "<first ~10 chars>...<last ~10 chars>"   # for selection_with_ellipsis; null if no specific section
   - Story 1.1: <summary>
+    prd_section: "<heading or user-story line>"
+    prd_anchor: "<start>...<end>"
     - Sub-task [<repo>]: <summary>
+      prd_section: "<heading or AC bullet>"
+      prd_anchor: "<start>...<end>"
     - ...
   - Story 1.2: ...
 
 ### Per-ticket validation
 - <ticket-id>: PASS | FAIL — <count> failures
-  - <gate-id>: <one-line reason and remediation>
+  prd_section: "<heading text>"
+  prd_anchor: "<start>...<end>"   # mirrored from Planned hierarchy for caller convenience
+  failures:
+    - gate: <gate-id>
+      category: <category from validator>
+      product_relevant: <true|false>
+      what: <plain-language description from validator>
+      recommendation: <1–3 candidate resolutions from validator>
 
 ### Verdict: PASS | FAIL
 ### Total failures: <n>
 ```
 
+`prd_anchor` and `prd_section` exist so downstream callers (notably `lisa:notion-prd-intake`) can post block-anchored Notion comments via `notion-create-comment` with `selection_with_ellipsis`. Build them as you parse the PRD: when you assign a planned ticket to a heading, user-story line, or AC bullet, capture the first ~10 and last ~10 characters of that section's text and emit them in the report. If a planned ticket genuinely doesn't trace to a specific section (cross-cutting infrastructure, derived sub-tasks), set both fields to `null` — the caller will fall back to a page-level comment.
+
+The `failures` array passes the validator's `Failure details` block through verbatim. Do not re-format `what` or `recommendation` here — those fields are already product-readable per the validator's contract, and re-summarizing risks losing concrete recommendations.
+
 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 `lisa:jira-write-ticket`

package/plugins/lisa/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: "Decompose a single PRD or specification into ordered work items in the configured tracker. Vendor-agnostic — the source can be a Notion PRD URL, an existing JIRA epic key, a markdown file, or a free-form description; the destination tracker is whatever the project is configured to use (JIRA today; Linear/GitHub Issues are pluggable). Single-PRD mode only — for batch scanning of all Status=Ready PRDs in a queue, use the lisa:intake skill."
+description: "Decompose a single PRD or specification into ordered work items in the configured tracker. Vendor-agnostic — the source can be a Notion PRD URL, a Confluence PRD URL, an existing JIRA epic key, a markdown file, or a free-form description; the destination tracker is whatever the project is configured to use (JIRA today; Linear/GitHub Issues are pluggable). Single-PRD mode only — for batch scanning of all Ready PRDs in a queue, use the lisa:intake skill."
 allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
 ---
 
@@ -22,6 +22,8 @@ Detect the input type from `$ARGUMENTS` and route to the appropriate source skil
 |------------------------|-------------|
 | A Notion **page** URL or page ID (single PRD) | `lisa:notion-to-jira` (with the PRD URL; runs the full pipeline: extract artifacts → walk live product → validate → write tickets → coverage audit) |
 | A Notion **database** URL or database ID | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a database. |
+| A Confluence **page** URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` (single PRD) | `lisa:confluence-to-jira` (with the PRD URL; same full pipeline as the Notion path) |
+| A Confluence **space** URL (`/wiki/spaces/<KEY>` with no `/pages/...`) | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a space. |
 | A JIRA ticket ID/URL of an Epic (existing epic *is* the spec) | `lisa:jira-agent` (read epic, decompose into stories/sub-tasks) |
 | A Linear / GitHub Issues URL or key | Not yet implemented. Stop and tell the user the adapter doesn't exist yet — the architecture supports it, but no `linear-prd-source` / `github-prd-source` skill has been built. Don't fall back. |
 | A file path (`@plan.md`, `./spec.md`) | Read the file as the spec; run the Plan flow's core decomposition with the file content as input. |