@codyswann/lisa 2.7.0 → 2.8.0

package/plugins/lisa/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/lisa/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`.

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

@@ -0,0 +1,304 @@
+---
+name: github-write-issue
+description: "Creates or updates a GitHub Issue following the same organizational best practices as lisa:jira-write-ticket — three-audience description, Gherkin acceptance criteria, parent sub-issue (Epic/Story hierarchy), explicit relationship discovery, remote links, labels for status/components/priority/story-points, and Validation Journey. Uses the `gh` CLI exclusively (no MCP). Rejects thin issues. The GitHub counterpart of lisa:jira-write-ticket."
+allowed-tools: ["Bash", "Skill", "Read"]
+---
+
+# Write GitHub Issue: $ARGUMENTS
+
+Create or update a GitHub Issue with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin issues are rejected.
+
+This skill is the GitHub counterpart of `lisa:jira-write-ticket`. The two skills share the same gates, description structure, acceptance-criteria format, and verification flow. The data-model translation is documented under "GitHub Issues data model" below — keep that table in sync with `lisa:github-validate-issue` so what one skill writes the other accepts.
+
+Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated (`gh auth status` must succeed). The skill never falls back to a different transport — if `gh` is unauthenticated, stop and surface the auth error.
+- `.lisa.config.json` must declare `github.org` and `github.repo` for the destination repository. The configured repo is the issue's home; pass it on every `gh` invocation via `--repo <org>/<repo>`.
+- `jq` installed (used to parse `gh` JSON outputs without hand-rolling parsers).
+
+## Phase 1 — Resolve Intent
+
+Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE:
+
+- **CREATE**: no existing issue ref provided.
+- **UPDATE**: an issue ref provided (`org/repo#<number>` or a full `https://github.com/<org>/<repo>/issues/<number>` URL). Call `lisa:github-read-issue <ref>` first to load the full current state before editing. Never overwrite without reading.
+
+Resolve `<ORG>` and `<REPO>` from the ref or from `.lisa.config.json`.
+
+## Phase 2 — Gather Required Inputs
+
+| Field | Required For | Notes |
+|-------|--------------|-------|
+| Issue type | CREATE | `Epic`, `Story`, `Task`, `Bug`, `Sub-task`, `Spike`, `Improvement`. Encoded as a label `type:<value>`. |
+| Summary (title) | CREATE, UPDATE | One line, imperative voice, under 100 chars. |
+| Description (body) | CREATE, UPDATE | Multi-section markdown — see Phase 3. |
+| Parent sub-issue | Non-bug, non-epic | Native GitHub sub-issue link. Enforced by `lisa:github-verify`. |
+| Priority | CREATE | Label `priority:<low|medium|high|critical>`. |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin in `## Acceptance Criteria` — see Phase 3. |
+| Validation Journey | Runtime-behavior changes | Delegate to `/github-add-journey`. |
+| Target backend environment | Runtime-behavior changes | Recorded under `## Target Backend Environment`. Skip only for doc / config / type-only. |
+| Sign-in account / credentials | Authenticated-surface tickets | Recorded under `## Sign-in Required`. |
+| Repository | Bug, Task, Sub-task | GitHub Issues live in exactly one repo by definition — record the repo name under `## Repository`, and reject any AC bullet that references a different repo. |
+
+Optional but recommended: assignee, milestone, components (label `component:<name>`), story points (label `points:<n>`), labels.
+
+Use `gh api repos/<org>/<repo>/labels --paginate` to discover existing labels before referencing one. If a required label doesn't exist (e.g., `type:Story`, `status:ready`, `priority:high`), create it via `gh label create <name> --color <hex> --description <desc> --repo <org>/<repo>`. The first run on a fresh repo will create the full label set; subsequent runs reuse them.
+
+## Phase 3 — Description Quality
+
+The description (issue body) MUST address three audiences. Reject and rewrite if any are missing.
+
+```markdown
+## Context / Business Value
+[Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
+ Link to the originating Slack thread, PRD page, incident, or customer report.]
+
+## Technical Approach
+[Developer-facing. Integration points, impacted modules, data model implications,
+ relevant tradeoffs. Not a full design doc — a pointer for someone picking it up.]
+
+## Acceptance Criteria
+```gherkin
+Scenario: <name>
+  Given <precondition>
+  When <action>
+  Then <observable outcome>
+
+Scenario: <name>
+  Given <precondition>
+  When <action>
+  Then <observable outcome>
+```
+
+## Out of Scope
+[Explicit list of what this issue does NOT cover. Forces scope discipline.]
+
+## Target Backend Environment
+[Required when the issue changes runtime behavior. One of: dev / staging / prod.
+ Skip section entirely for doc-only, config-only, or type-only issues.]
+
+## Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role, where to get the credentials (1Password item,
+ env var, seeded fixture), and any MFA/SSO notes.]
+
+## Repository
+[Required for Bug / Task / Sub-task. Name the single repo this issue covers.
+ If the work spans repos, this issue type is wrong — split into per-repo
+ Tasks/Sub-tasks under a parent Story or Epic.]
+
+## Source Artifacts
+[Group by domain (UI / UX flow / Data / Ops / Reference). One bullet per
+ artifact with title and URL. Inherited from the parent epic per the rules
+ in lisa:jira-source-artifacts.]
+
+## Source Precedence
+[When artifacts are attached, name the authoritative source per axis:
+ business rules → PRD body, visual treatment → mocks, flow → prototypes,
+ API/data → data artifacts. Cross-axis conflicts go under Open Questions.]
+
+## Links
+[Remote links: PRs (`Resolves <org>/<repo>#<pr>`), Confluence pages,
+ dashboards, incident tickets. Native `Resolves #<pr>` lines are picked up
+ by GitHub for auto-close.]
+
+## Relationship Search
+[Document the git+search outcomes from Phase 4b. "Searched git history
+ for `<keywords>` and `gh issue list` for label `component:X`; no related
+ work found." A no-result outcome is acceptable when documented.]
+
+## Validation Journey
+[Delegate to /github-add-journey if the issue changes runtime behavior.
+ Skip only for doc-only, config-only, or type-only issues.]
+```
+
+Rules:
+- Every acceptance criterion uses Given/When/Then. No vague "should work" language.
+- Every criterion is independently verifiable.
+- If the issue is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
+- If the issue is a Spike, include the question being answered and the definition of done.
+- If sign-in is required, the implementer must be able to sign in from the description alone.
+
+## Phase 4 — Relationship Discovery (Mandatory)
+
+### 4a. Parent sub-issue
+
+If the issue is not a Bug and not an Epic, it MUST have a parent sub-issue:
+
+1. If explicitly provided, use that issue number.
+2. Otherwise search active Epic issues:
+   ```bash
+   gh issue list --repo <org>/<repo> --label type:Epic --state open --json number,title,body --limit 100
+   ```
+   Match on keywords from the summary and description.
+3. If no Epic matches, stop and ask the human to create or pick one. Do NOT orphan the issue.
+
+### 4b. Related issues
+
+Run BOTH searches and document outcomes — never declare "no related work" without doing both.
+
+**Search 1: local git history**
+
+```bash
+git log --all --oneline --grep="<keyword>"
+git log --all --oneline -- <path-or-glob>
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If a PR or commit surfaces, capture the PR URL — it becomes a Phase 4c link.
+
+**Search 2: GitHub issue search**
+
+```bash
+gh issue list --repo <org>/<repo> --search "<keyword>" --state all --limit 50 --json number,title,state,labels,updatedAt
+gh issue list --repo <org>/<repo> --label "component:<component>" --state open --limit 100 --json number,title,state
+gh issue list --repo <org>/<repo> --search "epic:#<epic-number>" --state all --limit 50 --json number,title,state
+```
+
+For each candidate, classify the relationship using these markdown conventions in the issue body (under `## Links`):
+
+| Link type | How it's encoded |
+|-----------|------------------|
+| `blocks` | `Blocks #<number>` (or full `org/repo#<number>` for cross-repo) |
+| `is blocked by` | `Blocked by #<number>` |
+| `relates to` | `Relates to #<number>` |
+| `duplicates` | `Duplicates #<number>` (and close one as duplicate via `gh issue close <number> --reason "duplicate of #<other>"`) |
+| `clones` | `Cloned from #<number>` |
+
+GitHub does not have a native typed-link primitive for issues (only `Resolves #<pr>` for PR↔Issue). The text conventions above are parsed by `lisa:github-read-issue` to reconstruct the relationship graph.
+
+### 4c. Remote links
+
+Identify and attach (under `## Links`):
+- Related GitHub PRs, branches, or commits.
+- Confluence / Notion / Linear PRD pages (the originating PRD).
+- Dashboards (Grafana, Datadog, Sentry).
+- **Source artifacts from the originating PRD / parent Epic**: classify and inherit per `lisa:jira-source-artifacts`. Inherit by domain — UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`. Never assume a developer will walk up to the Epic to find design context.
+
+If the issue was generated from a PRD and the parent Epic has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction.
+
+### 4d. Source Precedence (must appear in description)
+
+Same rule as `lisa:jira-write-ticket` Phase 4d — record source precedence under `## Source Precedence` (or a paragraph under `## Technical Approach`) when artifacts are attached. Cross-axis conflicts go under `## Open Questions`.
+
+### 4e. Live Product Walkthrough Findings (UI-touching issues)
+
+If the issue modifies an existing user-facing surface, a `lisa:product-walkthrough` should already have been run upstream. Inherit findings under `## Current Product`.
+
+## Phase 5 — Set Metadata
+
+GitHub Issues uses **labels** for the structured metadata that JIRA stores in custom fields. Apply the conventions:
+
+| Concept | Label format | Example |
+|---------|--------------|---------|
+| Issue type | `type:<value>` | `type:Story`, `type:Bug`, `type:Epic`, `type:Sub-task`, `type:Spike`, `type:Improvement` |
+| Status | `status:<value>` | `status:ready`, `status:in-progress`, `status:code-review`, `status:on-dev`, `status:done` |
+| Priority | `priority:<value>` | `priority:low`, `priority:medium`, `priority:high`, `priority:critical` |
+| Components | `component:<name>` | `component:auth`, `component:billing` |
+| Story points | `points:<n>` | `points:3`, `points:5`, `points:8` |
+| Fix version | `fix-version:<value>` | `fix-version:2.7.0` |
+| Repo (multi-repo orgs) | implicit (issue lives in the repo) | — |
+| Triage marker | `claude-triaged-<repo>` | `claude-triaged-frontend-v2` |
+
+Milestones map to `fix-version:<value>` labels OR native GitHub Milestones — pick one convention per repo and document it in `.lisa.config.json` if needed. Default to labels for parity with the JIRA fix-version concept.
+
+Create labels lazily — call `gh label create` if a referenced label doesn't exist. Use a stable color palette per category so the issue board reads cleanly.
+
+## Phase 5.5 — Validate (Pre-write Gate)
+
+Before any write, invoke `lisa:github-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa:github-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
+
+`lisa:github-validate-issue` is the **single source of truth** for what makes a valid GitHub Issue in this pipeline — same gate definitions as `lisa:jira-validate-ticket`, translated to GitHub's data model. Do not re-implement gate logic here.
+
+If the validator reports `FAIL`, do NOT proceed to Phase 6. Fix the spec and re-run validation. Never call `gh issue create` while the validator's verdict is FAIL.
+
+## Phase 6 — Create or Update
+
+### CREATE
+
+1. Compose the body markdown from Phases 2/3/4 in a temp file (avoid quoting hell):
+   ```bash
+   gh issue create \
+     --repo <org>/<repo> \
+     --title "<summary>" \
+     --body-file /tmp/issue-body.md \
+     --label "type:<type>" --label "status:ready" --label "priority:<priority>" \
+     [--label "component:<name>" ...] [--milestone "<milestone>"] \
+     [--assignee "<login>"]
+   ```
+2. Capture the returned issue number.
+3. **Link to parent sub-issue** (if non-Epic): use the GraphQL sub-issue API.
+
+   Resolve the new issue's GraphQL node ID:
+   ```bash
+   child_id=$(gh api graphql -f query='query($org:String!,$repo:String!,$number:Int!){repository(owner:$org,name:$repo){issue(number:$number){id}}}' -F org=<org> -F repo=<repo> -F number=<new_number> --jq '.data.repository.issue.id')
+   ```
+   Resolve the parent issue's GraphQL node ID the same way. Then call:
+   ```bash
+   gh api graphql -f query='mutation($parentId:ID!,$childId:ID!){addSubIssue(input:{issueId:$parentId,subIssueId:$childId}){issue{number}subIssue{number}}}' -F parentId=$parent_id -F childId=$child_id
+   ```
+   If the GraphQL mutation isn't available on the repo (older GHES, sub-issues feature off), fall back to text linkage in the body (`Parent: #<parent>`) and surface a warning to the caller. Do NOT silently proceed without recording the parent.
+4. Phase 4b relationship lines (`Blocks #...`, `Blocked by #...`, etc.) are already in the body. No separate API call is needed — `lisa:github-read-issue` parses them on read.
+5. If the issue changes runtime behavior, invoke the `lisa:github-add-journey` skill to append the Validation Journey section.
+
+### UPDATE
+
+1. Re-read the current body via `gh issue view <number> --repo <org>/<repo> --json body --jq '.body'`. Edit only the sections being changed; preserve everything else verbatim.
+2. Apply the edit:
+   ```bash
+   gh issue edit <number> --repo <org>/<repo> --body-file /tmp/updated-body.md
+   ```
+3. Add labels: `gh issue edit <number> --add-label "<new-label>"`. Remove labels: `--remove-label`.
+4. Add new relationship lines to `## Links` if needed. Existing links are not touched unless explicitly removed.
+
+## Phase 7 — Verify
+
+Call the `lisa:github-verify` skill on the resulting issue. `lisa:github-verify` re-fetches the issue and runs `lisa:github-validate-issue` against the live state — same gates as Phase 5.5, applied to what GitHub actually stored.
+
+If it reports failures, fix them before returning.
+
+## Phase 8 — Announce
+
+Post a creation comment via `gh issue comment <number> --repo <org>/<repo> --body-file /tmp/announce.md` with:
+- `[<repo>]` prefix when the issue is repo-scoped (Bug / Task / Sub-task).
+- Who the issue is assigned to.
+- The relationships set in Phase 4b (`Blocks`, `Blocked by`, `Relates to`) with links.
+- Any remote PRs attached.
+
+Skip on UPDATE when no material change was made.
+
+## GitHub Issues data model
+
+The mapping below is the single source of truth for how JIRA concepts translate to GitHub Issues. Mirror this in `lisa:github-validate-issue` and `lisa:github-read-issue` so the shape is symmetric.
+
+| JIRA concept | GitHub Issues equivalent |
+|---|---|
+| Issue type | Label `type:<value>` |
+| Status (Ready / In Progress / Code Review / On Dev / Done) | Label `status:<value>` |
+| Epic / Story / Sub-task hierarchy | Native sub-issues via `gh api graphql addSubIssue` |
+| Acceptance Criteria | `## Acceptance Criteria` markdown section with a Gherkin code-fence |
+| Validation Journey | `## Validation Journey` markdown section |
+| Source artifacts | `## Source Artifacts` markdown section grouped by domain |
+| Epic parent | Native parent sub-issue link |
+| Issue links (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`) | Quick-action lines under `## Links`: `Blocks #N`, `Blocked by #N`, `Relates to #N`, `Duplicates #N`, `Cloned from #N` |
+| Remote links (PRs, dashboards) | Markdown links under `## Links` plus native `Resolves #<pr>` for PR↔Issue auto-close |
+| Components | Label `component:<name>` |
+| Fix version | Label `fix-version:<value>` (or native milestone) |
+| Story points | Label `points:<n>` |
+| Priority | Label `priority:<value>` |
+| Custom-field "Reporter" (the human) | The issue's `author` (immutable) plus the `Filed by:` line in the body |
+| Worklog | Comments (no native time tracking) |
+| Triage marker | Label `claude-triaged-<repo>` |
+
+## Rules
+
+- Never create a non-bug issue without a parent Epic / Story (sub-issue link).
+- Never skip relationship discovery — both git history AND `gh issue list` searches must run; outcomes documented under `## Relationship Search`. "None found" is acceptable only when documented.
+- Never create a Bug, Task, or Sub-task whose AC references work in a different repo. GitHub Issues already live in one repo; reject AC bullets that span others — split into per-repo issues under a shared Epic.
+- Never include a runtime-behavior issue without a target backend environment, and never include an authenticated-surface issue without sign-in credentials.
+- Never overwrite an issue body without reading the current version first.
+- All writes go through this skill (or the `tracker-write` shim). Other vendor-neutral skills must NEVER call `gh issue create` directly.
+- The gate logic lives in `lisa:github-validate-issue`, NOT here. This skill calls the validator at Phase 5.5 and Phase 7. When a gate needs to change, change it in `lisa:github-validate-issue`.
+- Never bypass the sub-issue mutation by encoding the parent only in the body. The native sub-issue link is what `lisa:github-read-issue` and the GitHub UI use to render the hierarchy.

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

@@ -17,10 +17,10 @@ When you do create the team, spawn every agent with `mode: "plan"` so they must
 
 $ARGUMENTS is either a url to a ticket containing the request, a pointer to a file containing the request, or the request in text format.
 
-If it's a ticket, use the appropriate vendor adapter to read and fully understand the request:
-- JIRA ticket → `lisa:jira-read-ticket` (preferred) or the Jira CLI
-- Linear ticket → the Linear CLI (no `lisa:linear-*` adapter built yet)
-- GitHub ticket → the Github CLI
+If it's a ticket, use `lisa:tracker-read` (preferred — vendor-agnostic; dispatches per `.lisa.config.json` `tracker`):
+- JIRA ticket → `lisa:tracker-read` → `lisa:jira-read-ticket`
+- GitHub Issue → `lisa:tracker-read` → `lisa:github-read-issue`
+- Linear ticket → the Linear CLI (no `lisa:linear-*` build-side adapter; Linear is a PRD source only)
 
 Capture comments and metadata, not just the description.