@codyswann/lisa 2.7.0 → 2.8.0

package/plugins/lisa/skills/github-read-issue/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: github-read-issue
+description: "Fetches the full scope of a GitHub Issue — metadata, body sections, all comments, native sub-issue parent and children, linked PRs, related issues parsed from `Blocks/Blocked by/Relates to/Duplicates/Cloned from` lines, and any cross-repo references. Produces a consolidated context bundle that downstream agents consume so they never act on an issue in isolation. The GitHub counterpart of lisa:jira-read-ticket."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Read GitHub Issue: $ARGUMENTS
+
+Fetch the full scope of the issue AND its related graph. Downstream agents must never act on an issue in isolation — always call this skill first so they see blockers, sibling sub-issues, linked PRs, and historical comments.
+
+This skill is the GitHub counterpart of `lisa:jira-read-ticket`. The output bundle structure mirrors the JIRA bundle so vendor-neutral consumers can parse either with minimal branching.
+
+Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.
+
+## Phase 1 — Resolve Context
+
+1. Confirm `gh auth status` succeeds.
+2. Parse `$ARGUMENTS`. Accept either:
+   - `<org>/<repo>#<number>` token, OR
+   - `https://github.com/<org>/<repo>/issues/<number>` URL.
+
+   If `$ARGUMENTS` is just `#<number>` or `<number>`, resolve `<org>/<repo>` from `.lisa.config.json` (`github.org` / `github.repo`).
+3. If the input doesn't parse cleanly, stop and report. Do NOT guess.
+
+## Phase 2 — Fetch Primary Issue
+
+```bash
+gh issue view <number> --repo <org>/<repo> --json number,title,body,state,stateReason,author,assignees,labels,milestone,createdAt,updatedAt,closedAt,url,comments,reactionGroups,projectItems
+```
+
+Extract and preserve:
+
+### Metadata
+
+- `number`, `title`, `state` (open/closed), `stateReason` (completed/not_planned/reopened/null)
+- `author` (immutable original reporter), `assignees`
+- All labels — partition by namespace: `type:<...>` (issue type), `status:<...>` (workflow status), `priority:<...>`, `component:<...>`, `points:<...>`, `fix-version:<...>`, `claude-triaged-<repo>`, plus any free-form labels
+- `milestone` (name + url)
+- `createdAt`, `updatedAt`, `closedAt`
+- `url` (canonical issue URL)
+
+### Body — parse markdown sections
+
+Walk the markdown body and capture each top-level `## ` section by name. Standard sections (per `lisa:github-write-issue` Phase 3):
+
+- `Context / Business Value`
+- `Technical Approach`
+- `Acceptance Criteria` (preserve the Gherkin code-fence verbatim)
+- `Out of Scope`
+- `Target Backend Environment`
+- `Sign-in Required`
+- `Repository`
+- `Source Artifacts`
+- `Source Precedence`
+- `Links`
+- `Relationship Search`
+- `Validation Journey` (preserve verbatim — pass through to verifier agents)
+- `Open Questions`
+- `Current Product`
+
+Any other `##` section: capture under `extra_sections` so callers can see PRDs that adopt non-standard sections.
+
+### Comments
+
+Fetch ALL comments. Do not truncate. The `comments` field from `gh issue view --json comments` includes author, body, createdAt for each. Flag comments that contain:
+- Credentials, reproduction steps
+- Status updates from stakeholders
+- Decisions
+- Triage headers like `[<repo>]`
+
+If pagination matters (issues with hundreds of comments), use `gh api repos/<org>/<repo>/issues/<number>/comments --paginate` to get the full set.
+
+## Phase 3 — Fetch Sub-issue Graph (Parent + Children)
+
+GitHub native sub-issues are exposed via GraphQL:
+
+```graphql
+query($org:String!,$repo:String!,$number:Int!){
+  repository(owner:$org,name:$repo){
+    issue(number:$number){
+      id
+      parent { number title state url repository { nameWithOwner } }
+      subIssues(first: 100) {
+        nodes {
+          number title state url
+          repository { nameWithOwner }
+          labels(first: 50) { nodes { name } }
+          assignees(first: 5) { nodes { login } }
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+gh api graphql -f query='<above>' -F org=<org> -F repo=<repo> -F number=<number>
+```
+
+Capture:
+- **Parent sub-issue**: number, title, state, url, repo.
+- **Child sub-issues**: list with number, title, state, url, repo, labels (especially `type:` and `status:`), assignees.
+
+If the GraphQL `parent` / `subIssues` fields aren't available (older GHES), fall back to parsing `Parent: #<n>` text in the body and recording sub-issue text references — note "GraphQL sub-issues unavailable" in the bundle so callers know parent-link is text-based.
+
+## Phase 4 — Parse Issue Links from Body
+
+The body's `## Links` section encodes typed relationships. Parse:
+
+| Pattern (case-insensitive) | Link type |
+|----------------------------|-----------|
+| `Blocks #<n>` or `Blocks <org>/<repo>#<n>` | `blocks` |
+| `Blocked by #<n>` or `Blocked by <org>/<repo>#<n>` | `is blocked by` |
+| `Relates to #<n>` or `Relates to <org>/<repo>#<n>` | `relates to` |
+| `Duplicates #<n>` or `Duplicates <org>/<repo>#<n>` | `duplicates` |
+| `Cloned from #<n>` or `Cloned from <org>/<repo>#<n>` | `clones` |
+| `Resolves #<n>` or `Closes #<n>` or `Fixes #<n>` (PR refs) | remote-link to PR |
+
+For each parsed reference, fetch the linked issue/PR:
+
+```bash
+gh issue view <link-number> --repo <link-org>/<link-repo> --json number,title,state,labels,assignees,url
+gh pr view <link-number> --repo <link-org>/<link-repo> --json number,title,state,reviewDecision,merged,mergedAt,url,reviewRequests,reviews,comments
+```
+
+For each linked **issue**, capture: number, title, state, type (from labels), status (from labels), assignees, url.
+
+For each linked **PR**, capture: number, title, state, mergedAt, reviewDecision, unresolved review comments, url.
+
+**Special handling for `is blocked by`:** include the linked issue's PR refs (parse `Resolves` lines in its body) and fetch each PR's state, so the agent knows whether the blocker is actually shipped.
+
+## Phase 5 — Fetch Sibling Sub-issues (Epic Context)
+
+If the primary issue has a parent sub-issue (i.e., is a Story / Task / Sub-task / Improvement under an Epic):
+
+1. Fetch the parent Epic in full via Phase 2 logic — full body, all comments, Validation Journey if present.
+2. Fetch the parent Epic's other sub-issues (siblings) via the same GraphQL `subIssues` query against the parent. Filter out the primary issue itself.
+3. For each sibling, capture: number, title, type label, status label, assignee, url. Read the first paragraph of each sibling's body for context. If a sibling has `status:in-progress` with an assignee different from the primary issue's assignee, **flag prominently** so the caller can avoid duplicate work.
+
+If the primary issue IS an Epic, capture all children via Phase 3's `subIssues` traversal (already done).
+
+## Phase 6 — Fetch Linked PRs (Native `Resolves` / Cross-references)
+
+GitHub's native `closingIssuesReferences` and timeline give the canonical PR↔Issue relationship:
+
+```bash
+gh api graphql -f query='query($org:String!,$repo:String!,$number:Int!){repository(owner:$org,name:$repo){issue(number:$number){closedByPullRequestsReferences(first:50){nodes{number title state merged mergedAt url repository{nameWithOwner}}}timelineItems(first:100,itemTypes:[CROSS_REFERENCED_EVENT]){nodes{...on CrossReferencedEvent{source{...on PullRequest{number title state url repository{nameWithOwner}}}}}}}}}' -F org=<org> -F repo=<repo> -F number=<number>
+```
+
+Capture: PR number, title, state, mergedAt, repo, url. Dedupe with PRs found in Phase 4.
+
+For each PR, fetch unresolved review comments via `gh pr view <num> --repo <org>/<repo> --json reviews,reviewThreads`.
+
+## Phase 7 — Assemble Context Bundle
+
+Produce a single structured output that the caller can pass verbatim to downstream agents. Use this format:
+
+```text
+# Issue Context: <org>/<repo>#<number>
+
+## Primary Issue
+- Ref: <org>/<repo>#<number>
+- URL: <url>
+- Type: <type from `type:` label>
+- Status: <status from `status:` label>
+- State: <open|closed> (<stateReason>)
+- Priority: <priority from `priority:` label>
+- Author: <login>
+- Assignees: <list>
+- Parent: <parent-ref> — <parent-title>  (or "None")
+- Milestone: <name>  (or "None")
+- Labels: <comma-separated raw labels>
+- Components: <list from `component:` labels>
+- Story points: <n from `points:` label>  (or "None")
+- Fix version: <from `fix-version:` label or milestone>
+- Created: <ISO> | Updated: <ISO> | Closed: <ISO or "—">
+
+### Body sections
+#### Context / Business Value
+<verbatim>
+
+#### Technical Approach
+<verbatim>
+
+#### Acceptance Criteria
+<verbatim, including the gherkin fence>
+
+#### Validation Journey
+<verbatim or "None">
+
+#### Out of Scope
+<verbatim>
+
+#### Source Artifacts / Source Precedence / Links / Relationship Search / Repository / Sign-in Required / Target Backend Environment / Open Questions / Current Product
+<each verbatim, omit those not present>
+
+### Comments (<count>)
+<chronological comments with author + ISO timestamp + body. Flagged items called out.>
+
+## Sub-issue graph
+### Parent
+<parent block: ref, title, state, url, type label> (or "None — this is an Epic / unparented")
+
+### Sub-issues (children, <count>)
+- <ref> — <type> — <status> — <state> — <title>
+  - <one-paragraph body summary>
+  - <FLAG: in progress by other assignee> if applicable
+
+## Linked Issues (parsed from body `## Links`)
+### Blocks (<count>)
+<per-issue block>
+
+### Is Blocked By (<count>)
+<per-issue block; include shipped/not-shipped state of any linked PRs>
+
+### Relates To (<count>)
+<per-issue block>
+
+### Duplicates / Clones
+<per-issue block>
+
+## Linked Pull Requests
+### Native (closedByPullRequestsReferences + cross-references)
+- <pr-ref> — <state> — <title> — <reviewDecision>
+  <body summary + unresolved review comments>
+
+### Body-referenced (`Resolves #<n>`)
+<per-PR block>
+
+## Sibling Sub-issues (other children of the same parent, <count>)
+- <ref> — <type> — <status> — <assignee> — <title>  **[FLAG: in progress by other assignee]**
+
+## Summary for Downstream
+- Full graph fetched: <issue-count>
+- Blockers still open: <list>
+- Related in-flight work: <list>
+- Relevant PRs: <list with state>
+```
+
+## Rules
+
+- Never summarize or truncate the primary issue's body or Validation Journey section.
+- Never skip a link type, even if it seems unrelated — the agent downstream decides relevance.
+- If a linked issue / PR returns an access error (private repo, deleted, etc.), capture the error and continue. Do not abort the read.
+- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
+- If the issue has no parent sub-issue, state this explicitly — do not silently skip Phase 5.
+- Output is pure context. This skill never modifies the issue.
+- The body parser must be tolerant of small format variations (different `##` casings, missing optional sections) but strict enough that downstream skills can rely on the named sections being present when they exist.

package/plugins/lisa/skills/github-sync/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: github-sync
+description: "Syncs plan progress to a linked GitHub Issue. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep issues in sync. The GitHub counterpart of lisa:jira-sync."
+allowed-tools: ["Bash", "Read", "Glob", "Grep"]
+---
+
+# GitHub Issue Sync
+
+Sync current plan progress to a GitHub Issue: `$ARGUMENTS`
+
+If no argument is provided, search for an issue ref (`org/repo#<number>` or `https://github.com/<org>/<repo>/issues/<n>` URL) in the active plan file (most recently modified `.md` in `plans/`).
+
+## Workflow
+
+### Step 1: Identify Issue and Context
+
+1. **Parse issue ref** from `$ARGUMENTS` or extract from the active plan file.
+2. **Fetch current issue state**:
+
+   ```bash
+   gh issue view <number> --repo <org>/<repo> --json number,title,state,labels,milestone,assignees,comments,url
+   ```
+
+3. **Determine current milestone** by checking:
+   - Does a plan file exist? → Plan created
+   - Is there a working branch? → Implementation started
+   - Are tasks in progress? → Active implementation
+   - Is there an open PR? → PR ready for review
+   - Is the PR merged? → Complete
+
+### Step 2: Gather Update Content
+
+| Milestone | Content to post |
+|-----------|-----------------|
+| **Plan created** | Plan summary, branch name, link to PR (if draft exists) |
+| **Implementation in progress** | Task completion summary (X of Y tasks done), any blockers |
+| **PR ready** | PR link, summary of changes, test results |
+| **PR merged** | Final summary, suggest moving issue to `status:done` |
+
+### Step 3: Post Update
+
+1. **Idempotency check** — read the issue's recent comments. If the most recent comment with the prefix `[claude-sync] <milestone>` matches the current milestone AND the body content is unchanged, skip the post (no duplicate).
+2. **Add the comment**:
+
+   ```bash
+   gh issue comment <number> --repo <org>/<repo> --body-file /tmp/sync-comment.md
+   ```
+
+   The body must start with `[claude-sync] <milestone>` so the next sync run can dedupe.
+
+3. **Report** to the user what was synced.
+
+### Step 4: Suggest Status Transition
+
+Based on the milestone, suggest (but do NOT automatically perform) a label transition:
+
+| Milestone | Suggested label |
+|-----------|-----------------|
+| Plan created | `status:in-progress` |
+| PR ready | `status:code-review` |
+| PR merged | `status:done` |
+
+The actual `status:in-progress` flip is owned by `lisa:github-build-intake` (claim) and `lisa:github-agent`. The `status:code-review` flip is owned by `lisa:github-evidence`. The `status:done` flip is typically owned by merge automation or PM. This skill never relabels.
+
+## Important Notes
+
+- **Never auto-transition labels** — always suggest and let the user / pipeline confirm.
+- **Idempotent updates** — the `[claude-sync] <milestone>` prefix on the most-recent comment is the dedupe key.
+- **Comment format** — use GitHub-flavored markdown (`##` headings, fenced code blocks). The same template is used for the JIRA path (rendered as wiki markup there); keep the markdown source canonical.
+
+## Execution
+
+Sync the issue now.

package/plugins/lisa/skills/github-to-tracker/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: github-to-tracker
+description: >
+  Break down a GitHub Issue PRD into Epics, Stories, and Sub-tasks in the configured destination tracker
+  (JIRA via lisa:tracker-write → lisa:jira-write-ticket, or GitHub Issues itself via lisa:tracker-write
+  → lisa:github-write-issue). Use this skill whenever the user shares a GitHub issue URL and wants it
+  converted into tickets, or asks to "break down this GitHub PRD", "create tickets from a GitHub issue",
+  or similar. This skill mirrors lisa:notion-to-tracker / lisa:confluence-to-tracker /
+  lisa:linear-to-tracker for projects whose PRDs live in GitHub Issues — the workflow, gates, dry-run
+  mode, and validation rules are identical; only the source-of-truth tool surface differs (the `gh` CLI
+  instead of Notion / Confluence / Linear MCP).
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# GitHub PRD to Tracker Breakdown
+
+Convert a GitHub Issue PRD into a structured ticket hierarchy in the configured destination tracker: Epics > Stories > Sub-tasks. Each Sub-task is scoped to exactly one repo and includes an empirical verification plan.
+
+This skill is the GitHub counterpart of `lisa:notion-to-tracker` / `lisa:confluence-to-tracker` / `lisa:linear-to-tracker`. The four skills share the same phases, gates, dry-run contract, and per-ticket validation logic. Only the PRD-side fetch tools differ. When changing workflow logic, change ALL FOUR skills together so the PRD vendors stay behaviorally identical.
+
+## What "PRD" means in GitHub Issues
+
+GitHub Issues has no native "PRD" entity. This skill treats a single GitHub Issue (carrying the `prd-ready` label) as the PRD container:
+
+- **Issue body** (markdown) is the PRD body — equivalent to a Notion page body, a Confluence page body, or a Linear project description.
+- **Sub-issues** (native GitHub sub-issues, traversable via `gh api graphql`) act as the candidate set for Epics or User Stories — the same role child Epic pages play in a Notion/Confluence PRD.
+- **Issue comments** capture decisions, engineering notes, product clarifications.
+- **Linked PRs** (parsed from `Resolves #<n>` lines and from native cross-references) provide implementation context.
+
+A multi-Epic PRD is encoded as a parent Issue with several child sub-issues. A simple PRD is a single Issue with body content only.
+
+## 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:github-prd-intake`) can decide whether to proceed.
+
+Dry-run output format is identical to `lisa:notion-to-tracker` / `lisa:confluence-to-tracker` / `lisa:linear-to-tracker`. Reuse the same fields, including `prd_anchor` and `prd_section`. For GitHub, `prd_anchor` is a section heading from the PRD body when the failure traces to a specific section; otherwise `null` (the caller posts unanchored failures as a rollup comment on the PRD issue).
+
+```text
+## github-to-tracker dry-run: <PRD title>
+
+### Planned hierarchy
+- Epic: <summary>
+  prd_section: "<heading text from the PRD body or sub-issue title that produced this epic>"
+  prd_anchor: "<heading text or sub-issue ref or null>"
+  - Story 1.1: <summary>
+    prd_section: "<heading or user-story line>"
+    prd_anchor: "<heading or sub-issue ref or null>"
+    - Sub-task [<repo>]: <summary>
+      prd_section: "<heading or AC bullet>"
+      prd_anchor: "<heading or sub-issue ref or null>"
+    - ...
+  - Story 1.2: ...
+
+### Per-ticket validation
+- <ticket-ref>: PASS | FAIL — <count> failures
+  prd_section: "<heading text>"
+  prd_anchor: "<heading or sub-issue ref or null>"
+  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 PRD issue, never adds/removes labels, never edits sub-issues, and never posts comments — that is the orchestrating skill's responsibility (`lisa:github-prd-intake`).
+
+## 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` shim. Never call `lisa:jira-write-ticket`, `lisa:github-write-issue`, `mcp__atlassian__createJiraIssue`, or `gh issue create` directly from this skill or from any sub-agent it spawns.**
+
+`lisa:tracker-write` enforces:
+- Vendor-agnostic dispatch (so a project's destination is one config edit away).
+- The vendor writer's pre-write gate (`lisa:tracker-validate` Phase 5.5).
+- Post-write verify (`lisa:tracker-verify`).
+- 3-audience description, Gherkin acceptance criteria, parent / Epic validation, link discovery, single-repo scope, sign-in / target environment fields, source-artifact preservation.
+
+Bypassing the shim layer produces tickets that the rest of the lifecycle (triage, verify, journey, evidence) treats as broken.
+
+The `gh` reads in this skill are limited to reading the source PRD issue, its sub-issues, and its comments. They never write.
+
+## Input
+
+A GitHub issue ref. The PRD is expected to have:
+
+- An issue body containing context, problems, and (optionally) a list of user stories.
+- One or more sub-issues that act as candidate Epics or user stories (optional — single-issue PRDs are valid).
+- Issue comments capturing engineering notes and product decisions.
+- The `prd-ready` label (if invoked from `lisa:github-prd-intake`; for ad-hoc / direct invocation the label is informational, not gating).
+
+URL parsing — accept either:
+
+- `org/repo#<number>`
+- `https://github.com/<org>/<repo>/issues/<number>`
+
+Resolve `<org>/<repo>` from `.lisa.config.json` if `$ARGUMENTS` is just `#<n>` or a bare number.
+
+## Configuration
+
+This skill reads project-specific configuration from environment variables and from `.lisa.config.json`. If these are not set, ask the user before proceeding — never invent values.
+
+| Variable / config | Purpose | Example |
+|-------------------|---------|---------|
+| `.lisa.config.json` `tracker` | Destination tracker (jira / github) | `github` |
+| `.lisa.config.json` `github.org` / `github.repo` | GitHub org/repo when tracker=github (and the source repo) | `acme` / `frontend-v2` |
+| `JIRA_PROJECT` | Destination JIRA project key when tracker=jira | `SE` |
+| `JIRA_SERVER` | Atlassian instance URL | `mycompany.atlassian.net` |
+| `E2E_TEST_PHONE` | Test user phone 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` |
+
+## Workflow
+
+### Phase 1: Fetch & Analyze the PRD
+
+1. **Confirm `gh auth status` succeeds.**
+2. **Fetch the PRD issue** via `gh issue view <num> --repo <org>/<repo> --json number,title,body,labels,milestone,assignees,author,createdAt,comments,url`. Capture title, body, labels, author, assignees, dates, comments.
+3. **Fetch native sub-issues** via the GraphQL `subIssues` traversal (see `lisa:github-read-issue` Phase 3). Each sub-issue's `{number, title, body, labels, state, url}` becomes a candidate epic / story node.
+4. **Recursively fetch grandchild sub-issues** (one more level — typical PRD depth is 2: PRD → Epic candidate → maybe a Story candidate). Stop after depth 3 unless the user explicitly requested deeper.
+5. **Fetch full comments per sub-issue** via `gh issue view <num> --repo <org>/<repo> --json comments` for every sub-issue surfaced in step 3. Capture body, author, timestamp.
+6. **Synthesize decisions and blockers** from the PRD body + every sub-issue body + every comment thread:
+   - Decisions already confirmed by the team (look for agreement in comments).
+   - Open questions that need product/engineering input.
+   - Engineering comments (prefixed with "Engineering:" or 🔧) that identify technical constraints.
+   - Cross-PRD dependencies (references to other GitHub issues, Notion / Confluence / Linear PRDs, 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 Notion / Confluence / Linear 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 body, every sub-issue body, and every comment** 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, peer Linear documents)
+   - 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 referenced in the body
+   - 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, and coverage smells.
+
+3. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. `source_page` lets you trace each reference back to where it appeared (PRD body vs a specific sub-issue vs a specific comment).
+
+4. **Surface coverage smells** as defined in `lisa:jira-source-artifacts` §5. Record 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-tracker` Phase 2 / `lisa:confluence-to-tracker` / `lisa:linear-to-tracker`. Two complementary inputs ground PRD analysis: the **code** and the **live product**.
+
+**2a. Codebase research.** If the session doesn't already have codebase context, explore the repos. Use Explore agents for repos not yet examined.
+
+**2b. Live product walkthrough.** If the PRD touches existing user-facing surfaces, invoke `lisa:product-walkthrough` 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.
+
+Walkthrough findings are surfaced back to product via the orchestrating intake skill (`lisa:github-prd-intake`), which posts them as a comment on the PRD issue. This skill itself does NOT post to GitHub — it only reads. The walkthrough section is also 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, body, artifacts) and validate it with `lisa:tracker-validate --spec-only`. Record the drafted spec (with a placeholder ref like `DRY-RUN-EPIC-1`) for Phase 4 to use as parent references. In `dry_run: false` mode, proceed as described below.
+
+For each epic identified in Phase 1, **invoke the `lisa:tracker-write` shim** (do not call `lisa:jira-write-ticket` or `lisa:github-write-issue` directly). Pass it everything it needs to enforce its quality gates:
+
+- `issue_type`: `Epic`
+- `summary`: epic title from the PRD
+- `body`: a draft of the multi-section description containing:
+  - **Context / Business Value**: epic summary from the PRD, originating GitHub PRD 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.
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
+
+Capture the returned epic ref — 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`. Draft each story spec and validate it with `lisa:tracker-validate --spec-only`. Use placeholder refs (e.g. `DRY-RUN-STORY-1.1`).
+
+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's structure or the source sub-issues)
+
+**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:
+
+- `issue_type`: `Story`
+- `parent_ref` / `epic_parent`: the Epic ref captured in Phase 3 (mandatory)
+- `summary`: prefixed per the naming convention above
+- `body`: multi-section description as in `lisa:notion-to-tracker` Phase 4
+- `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table:
+
+| 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 ref — Phase 5 needs it.
+
+### 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:tracker-write` for each sub-task — no agent may call `lisa:jira-write-ticket` / `lisa:github-write-issue` / `gh issue create` 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 / `## Source Artifacts` section / `## Links` section of every Epic and Story created in this run via `lisa:tracker-read`.
+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 refs 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 tracker-write" instruction is load-bearing — do not edit it out when adapting this template.**
+
+```text
+Create Sub-tasks via the configured destination tracker.
+
+CRITICAL: For each sub-task, invoke the `lisa:tracker-write` skill via the Skill tool.
+Do NOT call `lisa:jira-write-ticket`, `lisa:github-write-issue`, or `gh issue create` directly.
+The `lisa:tracker-write` shim dispatches to the configured destination AND enforces required
+quality gates (Gherkin acceptance criteria, multi-section 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_ref: the parent story ref
+- summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
+- body: a multi-section draft (Context / Technical Approach / Acceptance Criteria / etc.)
+- gherkin_acceptance_criteria: derived from the story's functional requirements
+- sign_in_account: [test user credentials from config]
+- 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.
+
+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 body.
+3. Be created via `lisa:tracker-write`, not via direct calls.
+
+If `lisa:tracker-write` rejects a sub-task, fix the input and re-invoke. Do NOT fall back
+to a direct vendor-write 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. Use `lisa:tracker-read` to search the destination for existing tickets in the same area before creating new ones for shared infrastructure.
+
+## GitHub-specific notes
+
+- **Body format**: GitHub Issues bodies are markdown. Treat headings (`#`, `##`, `###`) as section markers for `prd_section`.
+- **Native sub-issues**: GitHub native sub-issues (the `addSubIssue` GraphQL mutation) are how Epic→Story→Sub-task is encoded when the destination is also GitHub Issues. The PRD-side reads them via the `subIssues` GraphQL field.
+- **Comment threading**: GitHub Issues comments are flat — there's no `parentId` (unlike Linear). Decision context is captured by chronological position; quote the comment author + timestamp when surfacing it.
+- **Anchoring on PRD comments**: GitHub Issues do not have a Confluence-style selection-anchored inline-comment primitive. The orchestrating skill (`lisa:github-prd-intake`) approximates by quoting the relevant body excerpt at the top of each comment. The dry-run report's `prd_anchor` is the section heading the failure traces to (or `null` for body-wide failures).
+- **Self-host edge case**: when `tracker = "github"` AND the source PRD repo is the same as the destination repo, both reads and writes hit one place. The PRD carries `prd-*` labels; built tickets carry `type:*` + `status:*` labels. The two namespaces never overlap. `lisa:prd-ticket-coverage` filters out the source PRD itself when listing destination tickets.