@codyswann/lisa 2.119.0 → 2.121.0

package/plugins/lisa-copilot/skills/confluence-to-tracker/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: confluence-to-tracker
+description: >
+  Break down a Confluence PRD page into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json). Use this skill whenever the
+  user shares a Confluence PRD URL and wants it converted into tracker tickets, or asks to "break down
+  this Confluence spec", "create tickets from a Confluence page", "turn this Confluence doc into tickets",
+  or similar. This skill mirrors `lisa:notion-to-tracker` 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"]
+---
+
+# Confluence PRD to Tracker Breakdown
+
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Convert a Confluence PRD into a structured ticket hierarchy in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json): 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-tracker`. 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:tracker-write`, 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:tracker-validate` (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-tracker`'s. Reuse the same fields, including
+`prd_anchor` and `prd_section`. The only difference: `prd_anchor` is the inline-comment anchor text
+that `lisa:atlassian-access` `operation: comment-page kind: inline` accepts (typically the full
+selected substring; truncate if it exceeds the substrate's max anchor length and emit `null` if no
+resolvable anchor exists).
+
+```text
+## confluence-to-tracker 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 the destination tracker. It also never modifies the source Confluence
+page, never re-parents the PRD between lifecycle parents, and never posts comments — that is the
+orchestrating skill's responsibility (`lisa:confluence-prd-intake`).
+
+## PRD lifecycle is parent-page-based on Confluence
+
+Unlike GitHub and Linear (which use labels for PRD lifecycle state), Confluence encodes PRD lifecycle as **parent-page placement**: each lifecycle role (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`) corresponds to a dedicated parent page in the project's Confluence space, listed in `.lisa.config.json` under `confluence.parents.<role>`. A PRD's current state is determined by which of those parents it sits under; a "transition" is a `PUT /wiki/api/v2/pages/{id}` that swaps `parentId`.
+
+This skill itself does NOT transition the PRD between lifecycle parents — that is the orchestrating skill's job (`lisa:confluence-prd-intake`). This skill consumes the PRD content and produces tickets; lifecycle state changes (`ready` → `in_review`, `in_review` → `ticketed` / `blocked`) happen in the orchestrator, before and after this skill runs.
+
+Why parent-page-based, not label-based: scoped Atlassian API tokens cannot write Confluence labels via the v1 endpoint, and the v2 Label API group has no POST endpoint at all. Parent-id transitions, by contrast, are first-class in v2 and work with `write:page:confluence` scope. See `config-resolution` rule, section "Confluence PRD lifecycle uses parent pages, not labels," for the full rationale.
+
+## Hard Rule: All Writes Go Through `lisa:tracker-write`
+
+**Every ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa:tracker-write` skill. Never invoke `lisa:atlassian-access` write operations (`write-ticket`, `link`, `comment`, `transition`) directly from this skill or from any sub-agent it spawns.**
+
+`lisa:tracker-write` 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 / Improvement
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+Bypassing `lisa:tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. Read operations on Atlassian (ticket reads, JQL search, Confluence page reads, comment fetches) are still performed in this skill — but ONLY via `lisa:atlassian-access` (`operation: read-ticket | search-issues | read-page | search-pages | list-sites`), never via direct MCP tool calls or `acli`.
+
+## 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 configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key) and operational E2E test config from environment variables. See the `config-resolution` rule for the full schema.
+
+### From `.lisa.config.json`
+
+This skill is a **PRD source** (Confluence); destination tracker resolution is handled by `lisa:tracker-write` and `lisa:tracker-validate` internally — this skill does NOT read `tracker` directly. The relevant config for the source side:
+
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `atlassian.cloudId` | Atlassian Cloud site UUID for Confluence MCP calls | always |
+| `confluence.spaceKey` | Confluence space hosting PRDs | invoked without an explicit page URL (batch / arg-less mode) and `confluence.parentPageId` is unset |
+| `confluence.parentPageId` | Confluence parent page under which PRDs live | invoked without an explicit page URL (batch / arg-less mode) and `confluence.spaceKey` is unset |
+
+### From environment variables (E2E test config — operational, not tracker)
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `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. **Confirm the configured Atlassian site** by invoking `lisa:atlassian-access` `operation: list-sites` (it enforces connection match against `.lisa.config.json`).
+2. **Fetch the main PRD page** by invoking `lisa:atlassian-access` `operation: read-page id: <PAGE-ID>`. Capture body, parent page id (used by `lisa:confluence-prd-intake` to determine the PRD's lifecycle state — see "PRD lifecycle is parent-page-based" below), and child page references.
+3. **Identify all Epic child pages** by invoking `lisa:atlassian-access` `operation: read-page-descendants id: <PAGE-ID>` (one level deep first; recurse if the PRD nests epics under a "Specs" parent). If `atlassian-access` does not yet expose `read-page-descendants`, request its addition (see report at bottom).
+4. **Fetch all Epic pages** in parallel via `lisa:atlassian-access` `operation: read-page id: <EPIC-PAGE-ID>`.
+5. **Fetch full comments** for the main page and every epic page in parallel via `lisa:atlassian-access`:
+   - `operation: read-page-comments id: <PAGE-ID> kind: footer` — page-level threaded comments (equivalent to Notion's page-level discussions)
+   - `operation: read-page-comments id: <PAGE-ID> kind: inline` — block-anchored comments tied to specific text spans
+   - For any comment with replies, walk the tree via `operation: read-comment-children id: <COMMENT-ID>` until exhausted
+   (If any of these read-comment operations is not yet in `atlassian-access`'s dispatch table, request their addition — they are intentionally listed here so the access skill can be extended.)
+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:tracker-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:tracker-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:tracker-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:tracker-source-artifacts` §7. Encode it on every UI-touching story.
+
+### Phase 2: Codebase + Live Product Research
+
+Identical to `lisa:notion-to-tracker` 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 `lisa:atlassian-access` `operation: comment-page id: <PAGE-ID> kind: footer body: "..."`. 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:tracker-write` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `lisa:tracker-validate --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:tracker-write` skill** (do not invoke `lisa:atlassian-access` write operations directly). Pass it everything it needs to enforce its quality gates:
+
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
+- `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
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa:tracker-write` must not be passed `status:ready` for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready label is applied only in Phase 5.
+
+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:tracker-write` in this phase. Instead, draft each story spec and validate it with `lisa:tracker-validate --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:tracker-write`** with:
+
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
+- `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-tracker` 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 |
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass `status:ready` to `lisa:tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready label is applied only in Phase 5.
+
+Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
+
+### Phase 5: Create Sub-tasks
+
+**Auto-split cross-repo work before delegation.** For each candidate sub-task, apply `lisa:task-decomposition` step 1.5: if the work touches more than one repo, split it into one sub-task per repo under the same parent Story (e.g., `[backend-api] Add field` + `[mobile-app] Display field`), and encode the producer-before-consumer ordering via dependencies. Work units that may span repos (Epic, Story, Spike) stay as planned; work units that must be single-repo (Bug, Task, Sub-task, Improvement) are split now. Splitting is this skill's responsibility — the validator's S10 gate is `product_relevant: false` because cross-repo failures are decomposition errors caught here, not product questions sent back to the PRD.
+
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:tracker-write` for each sub-task — no agent may invoke `lisa:atlassian-access` write operations 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
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa:tracker-write` applies `status:ready` here so downstream build intake (`lisa:tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa:tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+
+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:tracker-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:tracker-source-artifacts`.
+
+To run the gate, this skill must:
+
+1. Pull the remote links of every epic and story created in this run via `lisa:tracker-read (vendor-neutral; dispatches to jira-read-ticket or github-read-issue)`.
+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:tracker-write` (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
+
+### Phase 7: PRD Back-link
+
+> **Mode guard**: In `dry_run: true` mode, skip this phase entirely — no tickets exist to link.
+
+After Phase 6, invoke the `lisa:prd-backlink` skill to write a `## Tickets` section back into the source Confluence PRD page. The section becomes the canonical anchor for the **Debrief** flow once the initiative ships.
+
+Invoke `lisa:prd-backlink` with:
+
+- `source_type: "confluence"`
+- `source_ref`: the original Confluence page URL
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+
+If `lisa:prd-backlink` fails (page permission denied, Confluence unreachable), surface the error in the Phase 6 report rather than aborting — the tickets are already created. Recommend the user re-run `lisa:prd-backlink` standalone once the source is reachable.
+
+## 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 lisa:tracker-write" instruction is load-bearing — do not edit it out when adapting this template.**
+
+```text
+Create sub-tasks in the [PROJECT] project.
+
+CRITICAL: For each sub-task, invoke the `lisa:tracker-write` skill via the Skill tool.
+Do NOT invoke `lisa:atlassian-access` write operations (write-ticket / link / comment /
+transition) directly. The `lisa:tracker-write` 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:tracker-write` 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:tracker-write`, not via direct `lisa:atlassian-access` write operations
+
+If `lisa:tracker-write` rejects a sub-task, fix the input and re-invoke. Do NOT fall back
+to a direct `lisa:atlassian-access` `operation: write-ticket` 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-copilot/skills/confluence-write-prd/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: confluence-write-prd
+description: "Creates or idempotently updates a PRD as a Confluence page parented under the configured lifecycle parent page (the draft parent by default, or the ready parent when initial_role is ready so lisa:confluence-prd-intake auto-claims it). The Confluence PRD-source writer behind lisa:prd-source-write. Confluence models PRD state by PARENT PAGE (not labels), per config-resolution. Dedupes by a stable marker embedded in the page body, found via CQL (matched by marker, never by title). All Atlassian access goes through lisa:atlassian-access."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# Write Confluence PRD: $ARGUMENTS
+
+Create (or update) a PRD page in Confluence. Invoked by `lisa:prd-source-write` when
+`source = confluence`; do not call directly from a vendor-neutral caller. **All Confluence
+operations go through `lisa:atlassian-access`** — never call the Atlassian API/MCP or `acli` directly.
+
+Confluence's PRD lifecycle uses **parent pages**, not labels (scoped API tokens can't write
+Confluence labels — see `config-resolution` "Confluence PRD lifecycle uses parent pages"). A PRD's
+state is which lifecycle parent it lives under; "promote to ready" = re-parent to the ready parent.
+
+`$ARGUMENTS` carries the `lisa:prd-source-write` spec: `title`, `body` (full PRD markdown),
+`initial_role` (`draft` | `ready`, default `draft`), `dedupe_key`, `marker`, optional `source_ref`.
+
+## Phase 1 — Resolve lifecycle parents
+
+```bash
+read_g() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv:-$2}}"; }
+SPACE=$(read_g '.confluence.spaceKey' '')
+CLOUDID=$(read_g '.atlassian.cloudId' '')
+[ -z "$CLOUDID" ] && { echo "Error: atlassian.cloudId not set in .lisa.config.json."; exit 1; }
+# Resolve the FULL set of lifecycle parents from config (never hard-code) — needed for the target
+# parent, the past-ready reverse-lookup, and to derive the space when spaceKey is absent.
+DRAFT_PARENT=$(read_g '.confluence.parents.draft' '')
+READY_PARENT=$(read_g '.confluence.parents.ready' '')
+IN_REVIEW_PARENT=$(read_g '.confluence.parents.in_review' '')
+BLOCKED_PARENT=$(read_g '.confluence.parents.blocked' '')
+TICKETED_PARENT=$(read_g '.confluence.parents.ticketed' '')
+SHIPPED_PARENT=$(read_g '.confluence.parents.shipped' '')
+VERIFIED_PARENT=$(read_g '.confluence.parents.verified' '')
+# "Progressed past ready" parents (never re-parent a PRD down from these):
+PROGRESSED_PARENTS=("$IN_REVIEW_PARENT" "$BLOCKED_PARENT" "$TICKETED_PARENT" "$SHIPPED_PARENT" "$VERIFIED_PARENT")
+```
+
+Resolve the target parent from `initial_role`: `ready` → `$READY_PARENT`, otherwise `$DRAFT_PARENT`.
+If the needed parent id is unset, stop and report that `/lisa:setup:confluence` must provision the
+lifecycle parent pages — do not create a PRD outside the lifecycle scaffolding.
+
+**Resolve the space (config allows parent-page-only setups with no `spaceKey`).** If `$SPACE` is
+empty, derive it from the target lifecycle parent: `lisa:atlassian-access` `operation: read-page id:
+<target parent>` and read its space key from the response. If neither `confluence.spaceKey` is set nor
+a space can be derived from the parent, **stop and report** that a space could not be established —
+do not attempt a CQL search or create without it.
+
+## Phase 2 — Dedupe by marker (CQL search before create)
+
+The `marker` is embedded in the page body. Find an existing PRD page carrying it — match the marker,
+**never** the title:
+
+```text
+lisa:atlassian-access  operation: search-pages  cql: 'space = "<SPACE>" AND text ~ "<marker>"'
+```
+
+If `source_ref` was passed, target that page directly. If a page with the marker exists → **update**;
+else → **create**.
+
+## Phase 3 — Create or update
+
+**Storage-format body + marker (both paths).** Convert the PRD markdown to Confluence **storage
+format** (XHTML): `#`/`##`/`###` → `<h1>/<h2>/<h3>`, paragraphs → `<p>`, lists → `<ul>/<ol><li>`,
+fenced code → `<ac:structured-macro ac:name="code">`. Embed the marker as a storage comment
+(`<!-- $MARKER -->`) or a small `<p>` so future CQL dedupe finds it. The body must always contain
+**exactly one** marker; never write a markerless page (CREATE or UPDATE). If the live page body
+already contains the canonical managed `## Lisa Usage` section, preserve it verbatim unless the
+caller intentionally supplied an updated canonical section; use the shared `usage-accounting`
+serializer/merge path rather than hand-editing ledger rows in storage XHTML.
+
+**CREATE:** `lisa:atlassian-access` `operation: write-page` (create form) with a payload that sets:
+- `title`: `$TITLE`
+- `space`: `$SPACE` (resolved in Phase 1)
+- `ancestors`/`parentId`: the resolved lifecycle parent (`$DRAFT_PARENT` or `$READY_PARENT`)
+- `body`: the storage-format, marker-normalized body above.
+
+**UPDATE** (existing page or `source_ref`):
+1. **GET-then-PUT** (load-bearing, as `confluence-prd-intake` documents): first `operation: read-page
+   id: <page-id>` to read the current `version.number`, then `operation: write-page` (edit form) with
+   the marker-normalized storage body and `version.number` bumped to current+1. A PUT without the
+   current version is rejected; never drop the marker or an existing managed `## Lisa Usage` section
+   on the edit.
+2. Re-parent to the target lifecycle parent if the role changed — **unless** the page's current
+   parent is in the resolved `${PROGRESSED_PARENTS[@]}` set (already past `ready`). If so, leave it
+   and report `reused (already past ready)`. Reverse-lookup the current parent in
+   `confluence.parents.*` to determine its role before re-parenting.
+
+## Phase 4 — Return
+
+```yaml
+ref: "<confluence-page-id>"
+url: "<page url>"
+role: draft | ready          # derived from the lifecycle parent the page now lives under (or its current role when reused past ready)
+marker: "<MARKER>"
+outcome: created | reused
+```
+
+## Rules
+
+- All access via `lisa:atlassian-access`; never call Atlassian directly.
+- State is the parent page, not a label — never attempt Confluence label writes (they 401 on scoped
+  tokens; see `config-resolution`).
+- Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
+- Never re-parent a PRD already past `ready` down to draft/ready.
+- Resolve parents from config (`confluence.parents.{draft,ready}`) — never hardcode page ids.

package/plugins/lisa-copilot/skills/debrief/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: debrief
+description: "Run the Debrief flow over a shipped initiative. Input: a PRD URL (Notion / Confluence / Linear / GitHub Issue / file), a JIRA epic key, or a GitHub epic issue URL. Output: a triage-ready learnings document covering every work item in the initiative — edge cases, gotchas, process friction, tooling gaps, convention drift — each with structured evidence and a human-disposition field. Persistence is deferred to lisa:debrief-apply."
+allowed-tools: ["Skill", "ToolSearch", "TeamCreate", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Debrief: $ARGUMENTS
+
+Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their PRs, and produce a triage-ready learnings document for human review.
+
+## Orchestration: agent team
+
+If you are NOT already operating inside an agent team (no prior successful team-creation or subagent-delegation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude: use `TeamCreate`. If `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
+
+Until the team is established, the first Codex teammate has been spawned, or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
+
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+| Input shape | Resolution |
+|-------------|------------|
+| Notion / Confluence / Linear / GitHub Issue PRD URL | Fetch the PRD; read its `## Tickets` (or equivalent) back-link section written by the Plan flow |
+| File path to a PRD markdown | Read the file; parse its `## Tickets` section |
+| JIRA epic key (e.g. `SE-1234`) or epic URL | Fetch the epic; list its child issues (Stories, Tasks, Bugs) |
+| GitHub epic issue URL or `<org>/<repo>#<n>` | Fetch the epic issue; list its sub-issues / linked items |
+
+If the PRD has no `## Tickets` section AND the input is not an epic, stop and report — the Plan flow's PRD back-link step (`lisa:prd-backlink`) was likely skipped. Suggest re-running Plan to populate the section, or pass the epic key directly.
+
+## Gate
+
+Run before mining begins:
+
+1. **All work items terminal.** Every linked work item must be in a terminal state (Done / Closed / Cancelled equivalent for the tracker). If any item is still open, stop and list the unfinished items — Debrief is post-shipping by definition.
+2. **PR coverage.** Every Done item that was implementable (Story / Task / Bug; not Spike) must have at least one merged PR linked. Items missing a PR are recorded as **anomalies** to surface in the report rather than silently excluded — a Done item with no PR is itself a learning ("how did this ship?").
+3. **Headless safety.** In headless / `-p` / scheduled mode, do not block on missing input — fail fast with a clear error listing what was needed.
+
+## Flow
+
+Execute the **Debrief** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gate, mining, synthesis, output, hand-off). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+The flow's mining step runs `tracker-mining-specialist` and `pr-mining-specialist` in parallel as separate tasks within the team. Both must complete before `learnings-synthesizer` runs. Express this with `blockedBy` so the synthesizer task is automatically gated on the two mining tasks.
+
+## Exhaustiveness expectation
+
+Debrief is deliberately exhaustive — the human, not the agent, decides what is worth keeping. Specialists should err toward surfacing more candidates, not fewer. A candidate that the synthesizer rates low confidence is still a row in the triage doc; only outright duplicates are dropped.
+
+## Output
+
+A markdown triage document at `./debrief/<initiative-slug>-<YYYY-MM-DD>.md` (or wherever the project's debrief output directory is configured) containing:
+
+1. **Header** — initiative name, source PRD/epic link, work-item count, PR count, generation date, gate results.
+2. **Anomalies** — work items missing PRs, items with abnormal status-transition timing, PRs with no review comments at all (signal-of-absence is a learning), etc.
+3. **Candidate learnings** — one row per candidate, grouped by category (Edge case / Recurring gotcha / Process friction / Tooling gap / Convention drift). Each row has:
+   - `Summary` — one sentence
+   - `Category`
+   - `Evidence` — links to the source ticket comment / PR comment / commit / test file (multiple allowed)
+   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "PROJECT_RULES.md", "memory: project_*.md", "new tooling-gap ticket")
+   - `Disposition` — empty checkbox-style field the human will fill: `[ ] Accept` / `[ ] Reject` / `[ ] Defer` plus a free-text reason
+4. **Source map** — appendix listing every work item and PR walked, so the human can verify completeness.
+
+Before returning, write the Debrief run's direct usage onto the triage document through
+`lisa:usage-accounting` so the markdown artifact carries its own `## Lisa Usage` section separate
+from delivery-time usage. If runtime usage is unavailable, record a debrief entry with
+`source: unavailable` and nullable token/cost fields instead of skipping the row.
+
+The skill's terminal output is the path to the triage document and a one-line summary of counts per category. Persistence does not happen here — that is `lisa:debrief-apply`'s job.
+
+## Hand-off
+
+After producing the triage document, print:
+
+```text
+Triage document written to: <path>
+Counts: <n> edge cases, <n> gotchas, <n> friction, <n> tooling gaps, <n> convention drift; <n> anomalies
+Next: human triage. When done, run `/lisa:debrief:apply <path>` to persist accepted learnings.
+```
+
+Then stop. Debrief never persists learnings on its own.

package/plugins/lisa-copilot/skills/debrief-apply/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: debrief-apply
+description: "Apply human-marked dispositions from a Debrief triage document. Reads the triage doc produced by lisa:debrief, parses each row's disposition (Accept / Reject / Defer), and routes Accepted items to their persistence destination. Deterministic and idempotent — safe to re-run if dispositions are added incrementally."
+allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
+---
+
+# Debrief Apply: $ARGUMENTS
+
+Read the triage document at `$ARGUMENTS` and persist every Accepted candidate learning to its destination.
+
+This skill is intentionally **single-agent** — there is no team. Routing is deterministic given the disposition column. Spawning sub-agents would only add latency.
+
+## Input
+
+A path or URL to a Debrief triage document produced by `lisa:debrief`. The document is expected to follow the structure that skill produces — a header, an anomalies section, candidate-learning rows grouped by category, and a source-map appendix.
+
+## Pre-flight
+
+1. **Verify the doc exists and parses.** If the file cannot be read or the expected sections are missing, stop and report — do not guess.
+2. **Confirm dispositions exist.** If every row is unmarked, stop and ask the human to triage first. A pristine doc is a no-op, not an error to silently swallow.
+3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), project-rules file (default: `.claude/rules/PROJECT_RULES.md`), memory directory (per the auto-memory system path), tracker for new tickets.
+
+## Routing rules
+
+For every row marked **Accept**:
+
+| Category | Destination | Action |
+|----------|-------------|--------|
+| Edge case | Edge Case Brainstorm checklist in `intent-routing.md` | Append the new pattern + question to the matching group (Navigation, Data, Failure, Input, Auth, or a new group if none fit). Use the row's `Summary` and `Evidence` link as a citation comment. |
+| Recurring gotcha | Memory file (`project_*.md`) | Write a new memory entry with `type: project`, structured as: rule, **Why:**, **How to apply:**. Add an index line to `MEMORY.md`. |
+| Process friction | Project rules file | Append a one-line guideline to `PROJECT_RULES.md` under an appropriate heading (or create one). |
+| Tooling gap | Configured tracker | Create a new ticket via `lisa:tracker-write` with `issue_type: Task`, summary derived from the row's `Summary`, description citing the evidence and the originating debrief doc. Label appropriately (`type:tooling`, `lifecycle-improvement`, etc.). |
+| Convention drift | `CLAUDE.md` (project) or `PROJECT_RULES.md` | Append the convention as a one-paragraph note under the relevant section. If no relevant section exists, create one. |
+
+For every row marked **Reject** or **Defer**: no action. Defer is a no-op for `apply` but worth surfacing in the run summary — the human may want to revisit at the next debrief.
+
+## Idempotency
+
+`apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint — before writing, check whether the destination already cites that fingerprint. If it does, skip the write and note the row as `already-applied` in the run summary. This lets the human triage a doc incrementally (mark a few, run apply, mark more, run apply again) without producing duplicates.
+
+## Updating the triage doc
+
+After each Accepted row is persisted, replace its `[ ] Accept` checkbox with `[x] Applied — <one-line summary of what was written>`. This makes the triage doc itself the audit log of what was acted on. If a write fails (e.g., tracker is unreachable), mark the row `[!] Apply failed — <reason>` and continue with the rest. Never abort the whole run because one row failed.
+
+## Output
+
+A run summary printed to the user:
+
+```text
+Applied <n> learnings:
+  <n> edge cases → intent-routing.md
+  <n> gotchas → memory
+  <n> friction → PROJECT_RULES.md
+  <n> tooling gaps → <tracker> (<key1>, <key2>, ...)
+  <n> convention drift → CLAUDE.md
+Skipped:
+  <n> rejected, <n> deferred, <n> already-applied
+Failed:
+  <n> (see <path> for details)
+Triage doc updated in place: <path>
+```
+
+If anything is written to a tracker, suggest the human commit the local file changes (memory, rules, intent-routing) when ready — `apply` does not commit.