@codyswann/lisa 2.6.4 → 2.8.0

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

package/plugins/src/base/skills/github-validate-issue/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: github-validate-issue
+description: "Validates a proposed GitHub Issue spec (or an existing issue) against the organizational quality gates without writing anything. Returns a structured PASS/FAIL report per gate with concrete remediation. The GitHub counterpart of lisa:jira-validate-ticket — same gate definitions, translated to the GitHub Issues data model. Single source of truth for what makes a valid GitHub Issue. Both the write path (github-write-issue runs it pre-write) and the dry-run path (github-to-tracker runs it during PRD intake) call this skill."
+allowed-tools: ["Bash", "Read"]
+---
+
+# Validate GitHub Issue: $ARGUMENTS
+
+Run all organizational quality gates against an issue spec OR an existing issue. **This skill is read-only — it never writes to GitHub.** The output is a structured report consumed by callers (`lisa:github-write-issue` for pre-write gating, `lisa:github-to-tracker` for PRD dry-run, `lisa:github-verify` for post-write checks).
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+1. **An existing issue ref** (`org/repo#<number>` or `https://github.com/<org>/<repo>/issues/<number>`): fetch it and validate the live state. Use this for post-write checks.
+2. **A proposed issue spec** (YAML block, see schema below): validate as-is without touching GitHub. Use this for pre-write and dry-run checks.
+
+### Spec schema
+
+Specs are passed as a fenced YAML block. Required keys depend on `issue_type`.
+
+```yaml
+issue_type: Story          # Story | Task | Bug | Epic | Spike | Sub-task | Improvement
+org: my-org
+repo: my-repo
+summary: "[CU-1.2] Upload contract PDF from settings"
+priority: medium
+parent_ref: "my-org/my-repo#1234"   # Parent Epic for non-Bug/non-Epic; Story for Sub-task
+body: |
+  ## Context / Business Value
+  ...
+
+  ## Technical Approach
+  ...
+
+  ## Acceptance Criteria
+  ```gherkin
+  Scenario: <name>
+    Given <precondition>
+    When <action>
+    Then <observable outcome>
+  ```
+
+  ## Out of Scope
+  ...
+
+  ## Target Backend Environment
+  dev
+
+  ## Sign-in Required
+  Account: ...
+
+  ## Repository
+  backend-api
+
+  ## Validation Journey
+  ...
+
+# Behavioral flags — caller asserts these so the validator can pick the right gates
+runtime_behavior_change: true     # → requires Target Backend Environment + Validation Journey
+authenticated_surface: true       # → requires Sign-in Required
+artifacts_attached: true          # → requires Source Precedence section
+links: [{ ref: "my-org/my-repo#99", type: "is blocked by" }]   # known issue links (may be empty)
+remote_links: [{ url: "https://github.com/.../pull/42", title: "PR #42" }]
+journey_followup: auto            # auto | none — see S11
+```
+
+If the caller passes only an issue ref, fetch via `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,state,milestone,assignees`, parse the body sections, derive the spec fields, then run gates. The parser lives in `lisa:github-read-issue` (composition).
+
+## Gates
+
+Gates are grouped into **Specification** (spec-only checks, no GitHub lookups) and **Feasibility** (requires GitHub lookups). The dry-run path may opt to run Specification gates only via `--spec-only`; the write path runs both.
+
+Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Categories are the same fixed set used by `lisa:jira-validate-ticket` so downstream PRD-intake comment-formatting policy is shared across vendors.
+
+| 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 Parent sub-issue 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 label exists in repo | `structural` | false |
+| F2 Parent sub-issue exists and is the right type | `structural` | false |
+| F3 Linked issues exist | `structural` | false |
+| F4 Required labels populated | `structural` | false |
+
+Category values are the same fixed set as `lisa:jira-validate-ticket`:
+
+- `product-clarity`, `acceptance-criteria`, `design-ux`, `scope`, `dependency`, `data`, `technical`, `structural`.
+
+### Specification Gates
+
+#### S1 — Required core fields
+
+`org`, `repo`, `issue_type`, `summary`, `priority`, `body` must all be present and non-empty.
+
+#### S2 — Summary format
+
+- Single line, ≤ 100 characters.
+- Imperative voice ("Add X", "Fix Y", not "Adding X" or "X is broken").
+- Bug / Task / Sub-task summaries SHOULD start with a `[repo-name]` prefix when the project convention uses one.
+
+#### S3 — Description has all three audiences
+
+Body must include all of these sections (case-insensitive `## ` headings):
+
+- `Context / Business Value` — stakeholder-facing
+- `Technical Approach` — developer-facing
+- `Acceptance Criteria` — coding-assistant-facing
+- `Out of Scope` — explicit non-coverage list
+
+Missing any → FAIL with name of missing section.
+
+#### S4 — Acceptance criteria in Gherkin
+
+Applies when `issue_type ∈ {Story, Task, Bug, Sub-task, Improvement}`.
+
+The `## Acceptance Criteria` section must contain at least one `Scenario:` block with `Given / When / Then` form, ideally inside a ` ```gherkin ` code fence. Reject prose-only criteria, "should work" language, or numbered lists without Given/When/Then verbs.
+
+#### S5 — Bug-specific content
+
+When `issue_type = Bug`, body must additionally include:
+
+- Reproduction steps
+- Expected vs. actual behavior
+- Environment where reproduced
+
+#### S6 — Spike-specific content
+
+When `issue_type = Spike`, body must include:
+
+- The question being answered
+- Definition of done (decision doc / prototype / findings deliverable)
+
+#### S7 — Parent sub-issue declared
+
+When `issue_type ∉ {Bug, Epic}`, `parent_ref` must be set. The native sub-issue link is set by `lisa:github-write-issue` Phase 6 step 3. (Validity of the parent is checked in feasibility gate F2.)
+
+#### S8 — Target Backend Environment
+
+When `runtime_behavior_change = true`, body must contain `## Target Backend Environment` with one of `dev`, `staging`, `prod`. Skipped for doc-only / config-only / type-only / Epic.
+
+#### S9 — Sign-in Required
+
+When `authenticated_surface = true`, body must contain `## Sign-in Required` naming the account/role and credential source.
+
+If the spec doesn't set `authenticated_surface`, infer it: scan the body and AC for sign-in / login / "as a {role} user" / authenticated route signals. If signals present and no `Sign-in Required` section: FAIL.
+
+#### S10 — Repository section, single-repo scope
+
+When `issue_type ∈ {Bug, Task, Sub-task}`, body must contain `## Repository` naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation to split into per-repo issues under a shared Epic.
+
+(GitHub Issues live in one repo by definition, so the `## Repository` section is technically redundant — keep it for parity with the JIRA path so downstream tooling sees the same shape.)
+
+Story / Epic / Spike / Improvement: skipped (may span repos).
+
+#### S11 — Validation Journey present
+
+When `runtime_behavior_change = true`, body must contain `## Validation Journey`. Skipped for doc-only / config-only / type-only / Epic.
+
+The caller controls strictness via `journey_followup`:
+- `auto` (default): missing section is FAIL with remediation `"Invoke lisa:github-add-journey to append the section after create"`. Callers like `lisa:github-write-issue` know to chain the followup automatically.
+- `none`: missing section is FAIL the caller will not auto-fix (used by dry-run paths).
+
+#### S12 — Source Precedence (when artifacts attached)
+
+When `artifacts_attached = true`, body must include source-precedence guidance covering: business rules → PRD body, visual treatment → mocks, flow → prototypes, API/data → data artifacts. Cross-axis conflicts surfaced under `## Open Questions`.
+
+Accept either placement:
+- A dedicated `## Source Precedence` subsection, OR
+- A "Source Precedence" / "authoritative source" paragraph under `## Technical Approach`.
+
+Detect by scanning for the phrase `Source Precedence` (case-insensitive) AND verifying the four axes (business rules, visual, flow, data) are each named.
+
+#### S13 — Relationship Search documented
+
+The issue must EITHER have at least one entry in `links`, OR the body must contain a `## Relationship Search` block listing the git history queries and `gh issue list` queries that were run with their outcomes. ("Searched git history for `<keywords>` and `gh issue list` for label `component:X`; no related work found.")
+
+An issue with zero links and no documented search: FAIL.
+
+### Feasibility Gates (require GitHub lookups; skip in `--spec-only`)
+
+#### F1 — Issue type label exists in repo
+
+```bash
+gh label list --repo <org>/<repo> --json name --jq '.[].name'
+```
+
+Confirm `type:<issue_type>` exists. Missing labels can be auto-created by `lisa:github-write-issue` Phase 5 — flag the absence as a structural FAIL with remediation "Run `gh label create type:<issue_type>` or let the write path auto-create."
+
+#### F2 — Parent sub-issue exists and is the right type
+
+When `parent_ref` is set:
+
+```bash
+gh issue view <number> --repo <org>/<repo> --json number,labels,state
+```
+
+Confirm the parent issue exists and:
+- For non-Sub-task children: parent has `type:Epic` label.
+- For Sub-task children: parent has `type:Story`, `type:Task`, `type:Bug`, or `type:Improvement` (anything that can host sub-tasks).
+
+#### F3 — Linked issues exist
+
+For each entry in `links`, run `gh issue view <number> --repo <link-org>/<link-repo>` to confirm the ref resolves. Flag broken refs.
+
+#### F4 — Required labels populated
+
+Per `Phase 5` of `lisa:github-write-issue`, every issue MUST carry: `type:<issue_type>`, `status:<status>`, `priority:<priority>`. If any are missing from the spec / live issue, FAIL with the missing label name.
+
+## Execution
+
+1. Parse `$ARGUMENTS`. If it's an issue ref, fetch via `gh issue view --json` and derive the spec fields. Otherwise parse the YAML spec.
+2. Confirm `gh auth status` succeeds before any feasibility gate runs.
+3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
+4. Unless the caller passed `--spec-only`, run every Feasibility gate.
+5. Emit the report below.
+
+## Output
+
+Output is a single fenced text block. Callers parse it; do not add free-form prose around it.
+
+```text
+## github-validate-issue: <ISSUE-REF-or-SUMMARY>
+
+### Specification Gates
+- [PASS|FAIL|N/A] S1 Required core fields — <one-line reason>
+- [PASS|FAIL|N/A] S2 Summary format — <one-line reason>
+- [PASS|FAIL|N/A] S3 Description three audiences — <one-line reason>
+- [PASS|FAIL|N/A] S4 Acceptance criteria in Gherkin — <one-line reason>
+- [PASS|FAIL|N/A] S5 Bug-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S6 Spike-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S7 Parent sub-issue declared — <one-line reason>
+- [PASS|FAIL|N/A] S8 Target Backend Environment — <one-line reason>
+- [PASS|FAIL|N/A] S9 Sign-in Required — <one-line reason>
+- [PASS|FAIL|N/A] S10 Single-repo scope — <one-line reason>
+- [PASS|FAIL|N/A] S11 Validation Journey — <one-line reason>
+- [PASS|FAIL|N/A] S12 Source Precedence — <one-line reason>
+- [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
+
+### Feasibility Gates  (omit this section when --spec-only)
+- [PASS|FAIL|N/A] F1 Issue type label exists in repo — <one-line reason>
+- [PASS|FAIL|N/A] F2 Parent sub-issue exists and is the right type — <one-line reason>
+- [PASS|FAIL|N/A] F3 Linked issues exist — <one-line reason>
+- [PASS|FAIL|N/A] F4 Required labels populated — <one-line reason>
+
+### Verdict: PASS | FAIL
+### Failures: <count>
+### 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, no gate IDs, no GitHub jargon — written for a non-engineer product owner>
+  recommendation: <1–3 concrete options the caller (or downstream product team) can pick from. Never "clarify this".>
+- gate: <gate-id>
+  ...
+```
+
+The verdict is `PASS` if every applicable gate is `PASS`. Any `FAIL` makes the verdict `FAIL`. `N/A` does not affect the verdict.
+
+### Failure-detail fields
+
+Same shape and meaning as `lisa:jira-validate-ticket` so downstream PRD-intake skills (Notion, Confluence, Linear, GitHub) can format comments uniformly:
+
+- **gate**: the gate ID (`S1`–`S13`, `F1`–`F4`).
+- **category**: the gate's fixed category from the table.
+- **product_relevant**: matches the gate's table entry. `false` means the failure is an internal data-quality problem the caller should fix without bothering product.
+- **what**: plain-language, product-readable.
+- **recommendation**: 1–3 concrete options.
+
+## Rules
+
+- Never write to GitHub. The `allowed-tools` list intentionally excludes any `gh issue create / edit / comment / close` invocation.
+- Never auto-fix the spec. This skill reports gaps; callers decide what to do.
+- Never silently skip a gate. Return `N/A` with the reason if a gate genuinely doesn't apply; never omit it.
+- The `what` and `recommendation` must be concrete and product-readable — vague guidance ("clarify this") is useless.
+- Never emit a category outside the fixed set.
+- `product_relevant` is determined by the gate, not by the failure context.
+- When validating an existing issue ref, parse the body via the same logic as `lisa:github-read-issue` so the two skills agree on what they see.

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

@@ -0,0 +1,29 @@
+---
+name: github-verify
+description: This skill should be used when verifying that a GitHub Issue meets organizational standards for parent-sub-issue relationships and description quality. It fetches the live issue and delegates the gate checks to github-validate-issue so the bar matches what github-write-issue enforces pre-write. The GitHub counterpart of lisa:jira-verify.
+allowed-tools: ["Skill", "Bash"]
+---
+
+# Verify GitHub Issue: $ARGUMENTS
+
+Verify that the existing GitHub Issue `$ARGUMENTS` (`org/repo#<number>` or full URL) meets organizational standards. This skill is a thin post-write wrapper around `lisa:github-validate-issue`: it fetches the live issue and asks the validator to run the gates against the fetched state.
+
+This indirection exists so the gate definitions live in exactly one place (`lisa:github-validate-issue`). When the bar changes, change it there — `lisa:github-verify`, `lisa:github-write-issue` (Phase 5.5 pre-write), and `lisa:github-to-tracker` (PRD dry-run) all pick it up.
+
+## Process
+
+1. Confirm `gh auth status` succeeds.
+2. Parse `$ARGUMENTS`. Resolve `<org>`, `<repo>`, `<number>`.
+3. Fetch the issue via `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,state,milestone,assignees,author,createdAt,updatedAt,closed,closedAt,url`.
+4. Invoke `lisa:github-validate-issue` and pass the issue ref. The validator fetches its own copy and runs every gate (Specification + Feasibility) against the live state.
+5. Surface the validator's report verbatim to the caller.
+
+## Output
+
+Pass through `lisa:github-validate-issue`'s structured output unchanged. Do not summarize or paraphrase — downstream callers (e.g. `lisa:github-agent`'s pre-flight gate) parse the gate lines.
+
+## Notes
+
+- This skill is read-only. It never edits the issue, posts comments, or changes labels.
+- If a gate fails, the recommendation is part of the validator's report; surface it as-is.
+- The Validation Journey check (S11) parses the `## Validation Journey` markdown section — same parser logic as `lisa:github-add-journey` and `lisa:github-journey`.