@codyswann/lisa 2.189.7 → 2.189.8

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

@@ -0,0 +1,317 @@
+---
+name: lisa-jira-validate-ticket
+description: "Validates a proposed JIRA ticket spec (or an existing ticket) against the organizational quality gates without writing anything. Returns a structured PASS/FAIL report per gate with concrete remediation. This is the single source of truth for what makes a valid ticket — both the write path (jira-write-ticket runs it pre-write) and the dry-run path (notion-to-tracker runs it during PRD intake) call this skill so the bar can never drift."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Validate JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa-atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Run all organizational quality gates against a ticket spec OR an existing ticket. **This skill is read-only — it never writes to JIRA.** The output is a structured report consumed by callers (`lisa-jira-write-ticket` for pre-write gating, `lisa-notion-to-tracker` for PRD dry-run, `lisa-jira-verify` for post-write checks).
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+1. **An existing ticket key** (e.g. `PROJ-1234`): fetch it and validate the live state. Use this for post-write checks.
+2. **A proposed ticket spec** (YAML block, see schema below): validate as-is without touching JIRA. 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
+project_key: SE
+summary: "[CU-1.2] Upload contract PDF from settings"
+priority: Medium
+parent_key: SE-1234        # Epic key for non-Bug/non-Epic; Story key for Sub-task
+description: |             # Full description text — every required section
+  h2. Context / Business Value
+  ...
+
+  h2. Technical Approach
+  ...
+
+  h2. Acceptance Criteria
+  # Given <precondition>
+    When <action>
+    Then <observable outcome>
+
+  h2. Out of Scope
+  ...
+
+  h2. Target Backend Environment
+  dev
+
+  h2. Sign-in Required
+  Account: ...
+
+  h2. Repository
+  backend-api
+
+  h2. 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: [{ key: "PROJ-99", type: "is blocked by" }]   # known issue links (may be empty)
+remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
+build_ready: true                 # caller asserts the build-ready role (status:ready) is/would be applied — see S15
+child_refs: ["PROJ-601", "PROJ-602"]   # known child work (sub-tasks / "is blocked by" parentage) — see S15
+```
+
+If the caller passes only a ticket key, fetch the ticket via `lisa-atlassian-access` `operation: read-ticket key: <KEY>`, derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa-jira-read-ticket`) so S15 can classify the ticket — then run gates.
+
+## Gates
+
+Gates are grouped into **Specification** (spec-only checks, no JIRA lookups) and **Feasibility** (requires JIRA lookups). The dry-run path may opt to run Specification gates only; the write path runs both.
+
+Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Categories drive how downstream callers (notably `lisa-notion-prd-intake`) translate failures into product-facing comments; `product_relevant=false` failures indicate internal data-quality problems (broken parent links, missing core fields) that the agent should fix itself rather than ask product to clarify.
+
+| Gate | Category | Product-relevant |
+|------|----------|------------------|
+| S1 Required core fields | `structural` | false |
+| S2 Summary format | `structural` | false |
+| S3 Description three audiences | `product-clarity` | true |
+| S4 Acceptance criteria in Gherkin | `acceptance-criteria` | true |
+| S5 Bug-specific content | `product-clarity` | true |
+| S6 Spike-specific content | `scope` | true |
+| S7 Epic parent declared | `structural` | false |
+| S8 Target Backend Environment | `technical` | false |
+| S9 Sign-in Required | `technical` | false |
+| S10 Single-repo scope | `scope` | false |
+| S11 Validation Journey | `acceptance-criteria` | true |
+| S12 Source Precedence | `design-ux` | true |
+| S13 Relationship Search | `dependency` | true |
+| S14 Evidence manifest binding (leaf work units) | `acceptance-criteria` | true |
+| S15 Leaf-only build-ready | `structural` | false |
+| F1 Issue type valid in project | `structural` | false |
+| F2 Epic parent exists and is an Epic | `structural` | false |
+| F3 Linked tickets exist | `structural` | false |
+| F4 Required custom fields populated | `structural` | false |
+
+Category values are drawn from this fixed set:
+
+- `product-clarity` — feature behavior or user intent unclear in the PRD
+- `acceptance-criteria` — pass/fail conditions missing or ambiguous
+- `design-ux` — visual or interaction spec missing
+- `scope` — boundary unclear, items overlap, split needed
+- `dependency` — blocked by another team / system / decision
+- `data` — data source / shape / volume unspecified
+- `technical` — engineering decision required (rare from PRD path; mostly internal)
+- `structural` — internal data-quality problem the agent must fix itself, not surface to product
+
+### Specification Gates
+
+#### S1 — Required core fields
+
+`project_key`, `issue_type`, `summary`, `priority`, `description` 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
+
+Description text must include all of these sections. For proposed specs, detect case-insensitive Markdown/wiki headings (`##` or `h2.`). For live JIRA tickets, extract section headings from ADF `heading` nodes first and fail if the description is one literal Markdown/wiki paragraph instead of structured ADF heading nodes:
+- `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 criterion in `Given / When / Then` form. Reject prose-only criteria, "should work" language, or numbered lists without Given/When/Then verbs.
+
+#### S5 — Bug-specific content
+
+When `issue_type = Bug`, description must additionally include:
+- Reproduction steps
+- Expected vs. actual behavior
+- Environment where reproduced
+
+#### S6 — Spike-specific content
+
+When `issue_type = Spike`, description must include:
+- The question being answered
+- Definition of done (decision doc / prototype / findings deliverable)
+
+#### S7 — Epic parent declared
+
+When `issue_type ∉ {Bug, Epic}`, `parent_key` must be set — **except for a build-ready leaf work unit**, which may stand alone. A flat `Task` / `Improvement`, or a childless `Story` / `Spike` (no open child work) with `build_ready = true`, is an independently claimable leaf per `leaf-only-lifecycle`, which states such leaves "must not be stranded"; for these a missing parent is `N/A`, not a FAIL. This mirrors the leaf carve-out already in S10/S15. A `Sub-task` is exempt from this exception — it always requires a parent. (Validity of a declared parent key is checked in feasibility gates.)
+
+#### S8 — Target Backend Environment
+
+When `runtime_behavior_change = true`, description must contain a `Target Backend Environment` section (`h2.` / `##` in proposed text, or an ADF heading in live JIRA) with one of `dev`, `staging`, `prod`. Skipped for doc-only / config-only / type-only / Epic.
+
+#### S9 — Sign-in Required
+
+When `authenticated_surface = true`, description must contain `h2. Sign-in Required` naming the account/role and credential source (1Password item, env var, seeded fixture).
+
+If the spec doesn't set `authenticated_surface`, infer it: scan the description 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, Improvement}` — or a **build-ready childless Story/Spike** (a claimable leaf per `leaf-only-lifecycle`) — description must contain a `Repository` section (`h2.` / `##` in proposed text, or an ADF heading in live JIRA) naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation `"Split into per-repo work units under a shared parent Story (see lisa-task-decomposition step 1.5)"`.
+
+An **Epic**, or a **Story/Spike that still holds child work** (or is not build-ready): skipped (may span repos — coordination containers, not claimable leaf work units).
+
+This gate is `product_relevant: false` because cross-repo work units are not a product question — they are a decomposition error. Callers (`lisa-notion-to-tracker`, `lisa-confluence-to-tracker`, `lisa-linear-to-tracker`, `lisa-github-to-tracker`) MUST pre-split cross-repo work into per-repo work units during the decomposition phase per `lisa-task-decomposition` step 1.5; an S10 failure here indicates the agent skipped that step and must auto-split + revalidate before writing, not surface a clarifying comment to product.
+
+#### S11 — Validation Journey present
+
+When `runtime_behavior_change = true`, description must contain a `Validation Journey` section (`h2.` / `##` in proposed text, or an ADF heading in live JIRA). Skipped for doc-only / config-only / type-only / Epic.
+
+The caller controls the strictness by passing `journey_followup: "auto"` or `journey_followup: "none"` in the spec:
+- `auto` (default): if the section is absent, return `FAIL` with remediation `"Invoke lisa-jira-add-journey to append the section after create"`. Callers like `lisa-jira-write-ticket` know to chain `lisa-jira-add-journey` automatically, so this counts as a fixable failure they can resolve in-line — they re-run validation after appending.
+- `none`: missing section is a `FAIL` that the caller will not auto-fix, so the verdict gates progress (used by dry-run paths like `lisa-notion-to-tracker` PRD intake, where there's no agent standing by to add the journey).
+
+Either way the gate emits `FAIL`, not a third state. Strictness is the caller's policy, not the validator's.
+
+#### S12 — Source Precedence (when artifacts attached)
+
+When `artifacts_attached = true`, description 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 — both are valid per `lisa-tracker-source-artifacts`:
+- A dedicated `## Source Precedence` (or `h2. Source Precedence`) subsection, OR
+- A "Source Precedence" / "source precedence" / "authoritative source" paragraph under `Technical Approach` that covers the four axes above.
+
+Detect by scanning for the phrase `Source Precedence` (case-insensitive) anywhere in the description, AND verifying the four axes (business rules, visual, flow, data) are each named. Missing the phrase OR missing one or more axes: FAIL with a remediation that names the missing axes.
+
+#### S13 — Relationship Search documented
+
+The ticket must EITHER have at least one issue link in `links`, OR the description / a comment must contain a `## Relationship Search` block listing the git history queries and JQL queries that were run with their outcomes ("Searched git history for `<keywords>` and JQL for component=`X`; no related work found.").
+
+A ticket with zero links and no documented search: FAIL.
+
+#### S14 — Evidence manifest binding (leaf work units)
+
+When `issue_type ∈ {Bug, Task, Sub-task, Improvement}` AND `runtime_behavior_change = true`, the `h2. Validation Journey` must declare at least one `[EVIDENCE: name]` marker. Each marker name must be kebab-case and unique within the ticket. These markers are the work unit's **evidence manifest** — the exact, enumerated set of artifacts that must be captured and attached before the ticket may be marked complete (see the "Per-Work-Unit Evidence Contract" section of the `verification` rule, the Definition of Done in `verification-lifecycle`, and the evidence-manifest gate in `tracker-evidence`).
+
+FAIL when the Validation Journey is present but declares zero `[EVIDENCE: name]` markers, or when any marker name is empty, duplicated, or not kebab-case. A behavior-changing work unit SHOULD declare both a success marker and an error/edge marker; a journey with only one marker passes but the remediation should recommend adding the error/edge case.
+
+This gate depends on S11. It is `N/A` for containers — an **Epic**, or any item with open child work (coordination containers, not work units) — and for leaf units with `runtime_behavior_change = false` (doc-only / config-only / type-only). If S11 fails because the Validation Journey is absent, S14 also FAILs (there is no manifest to bind) with remediation pointing back to `lisa-jira-add-journey`.
+
+#### S15 — Leaf-only build-ready
+
+Enforces the build-side of the vendor-neutral `leaf-only-lifecycle` rule: **only a leaf work unit may carry the build-ready role.** This is the symmetric write-side guard for the JIRA validator — a stale or hand-applied `status:ready` label on a container is a lifecycle error and must FAIL here, regardless of how the ticket was produced. (Mirrors the "Build-ready label is leaf-only" rule that `lisa-jira-write-ticket` applies at write time.)
+
+**When the gate applies.** Run S15 whenever the ticket is build-ready — i.e. `build_ready = true`, or the spec/live labels include `status:ready`. If the ticket is not build-ready, S15 is `N/A` (nothing claims a non-ready ticket, so the invariant is vacuous).
+
+**Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an item is a **container** if it has child work, whatever its declared type; otherwise the **issue type** decides. Determine child work from (in order) `child_refs`, native sub-tasks, and `is blocked by` / parent references — the same hierarchy resolution `lisa-jira-read-ticket` uses. When validating a live key, query sub-tasks alongside the ticket fetch.
+
+Apply this decision and FAIL the two invariant-violating cases:
+
+1. **Container with child work + build-ready** — child work is present (any type that has open children), AND build-ready. FAIL. A parent organizes work; it is never claimed and implemented directly. Its lifecycle state rolls up from its children.
+2. **Childless Epic + build-ready** — `issue_type = Epic` with **no** child work, AND build-ready. Still FAIL: an Epic is a pure rollup container by design, and a childless one is an incomplete decomposition or a mis-applied role, not an implementable unit. (A childless Story or Spike is **not** failed here — the childless-parent exception in `leaf-only-lifecycle` promotes every childless non-Epic type to a build-ready leaf.)
+
+PASS (the childless-parent exception) when the ticket is build-ready and is a **leaf work unit**: it has **no** open child work and `issue_type ≠ Epic` (i.e. `Bug, Task, Sub-task, Improvement`, or a childless `Story` / `Spike`). A flat Task/Bug, or a childless Story/Spike with no sub-tasks, is a valid build-ready leaf and must not be stranded.
+
+| issue_type | has child work | build-ready | S15 |
+|---|---|---|---|
+| Bug / Task / Sub-task / Improvement / Story / Spike | no | yes | **PASS** (leaf) |
+| any type | yes | yes | **FAIL** (structurally a container) |
+| Epic | no | yes | **FAIL** (childless Epic — pure rollup container, exception does not apply) |
+| any | any | no | **N/A** (not build-ready) |
+
+Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle. Move status:ready off this container onto its leaf children (or, for a childless Epic, decompose it into leaf children or reclassify it to a leaf type); a parent's lifecycle state rolls up from its children and is never set to ready directly."`
+
+`product_relevant: false` — a build-ready container is a lifecycle/decomposition error for the caller to repair, not a product question.
+
+### Feasibility Gates (require JIRA lookups; skip in dry-run if requested)
+
+#### F1 — Issue type valid in project
+
+Invoke `lisa-atlassian-access` to fetch issue-type metadata for `project_key` and confirm `issue_type` exists.
+
+#### F2 — Epic parent exists and is an Epic
+
+When `parent_key` is set for non-Sub-task: fetch via `lisa-atlassian-access` `operation: read-ticket key: <parent_key>`, confirm the issue type is `Epic`. For Sub-task, confirm the parent is a non-Sub-task in the same project.
+
+#### F3 — Linked tickets exist
+
+For each entry in `links`, invoke `lisa-atlassian-access` `operation: read-ticket key: <link.key>` to confirm the key resolves. Flag broken keys.
+
+#### F4 — Required custom fields populated
+
+Use the same project-issue-type-metadata lookup from F1 (via `lisa-atlassian-access`) to learn required custom fields for the issue type. Any required custom field not provided in the spec: FAIL.
+
+## Execution
+
+1. Parse `$ARGUMENTS`. If it's a ticket key, fetch the ticket via `lisa-atlassian-access` `operation: read-ticket` and derive the spec from the fetched fields — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa-jira-read-ticket`) so S15 can classify the ticket. When the fetched description is ADF, walk the document tree and extract section headings from ADF `heading` nodes, then collect the text between heading nodes for section-specific gates. If the fetched description is a single paragraph containing literal Markdown/wiki heading markers, treat that as a formatting failure rather than accepting substring matches. Otherwise parse the YAML spec.
+2. If any feasibility gate will run, invoke `lisa-atlassian-access` `operation: list-sites` once to confirm the configured site is reachable (it enforces connection match against `.lisa.config.json`).
+3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
+4. Unless the caller passed `--spec-only` (dry-run), run every Feasibility gate. Collect results.
+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
+## jira-validate-ticket: <TICKET-KEY-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 Epic parent 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>
+- [PASS|FAIL|N/A] S14 Evidence manifest binding — <one-line reason>
+- [PASS|FAIL|N/A] S15 Leaf-only build-ready — <one-line reason>
+
+### Feasibility Gates  (omit this section when --spec-only)
+- [PASS|FAIL|N/A] F1 Issue type valid in project — <one-line reason>
+- [PASS|FAIL|N/A] F2 Epic parent exists and is an Epic — <one-line reason>
+- [PASS|FAIL|N/A] F3 Linked tickets exist — <one-line reason>
+- [PASS|FAIL|N/A] F4 Required custom fields 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 of what is missing or wrong, no gate-IDs, no JIRA terminology — written so a non-engineer product owner understands the issue>
+  recommendation: <1–3 concrete options the caller (or downstream product team) can pick from. Never "clarify this" — always a specific suggested resolution.>
+- gate: <gate-id>
+  category: ...
+  ...
+```
+
+The verdict is `PASS` if and only if every applicable gate is `PASS`. Any `FAIL` makes the verdict `FAIL`. `N/A` does not affect the verdict.
+
+### Failure-detail fields
+
+- **gate**: the gate ID (`S1`–`S15`, `F1`–`F4`).
+- **category**: the gate's fixed category from the table above. Callers use this to label or filter comments — `product-clarity`, `acceptance-criteria`, `design-ux`, `scope`, `dependency`, `data`, `technical`, or `structural`.
+- **product_relevant**: matches the gate's table entry. `false` means the failure is an internal data-quality problem (e.g., the agent built a malformed spec, an issue type is invalid in the project) and the caller should fix it without bothering the product team. `true` means the PRD needs product input to resolve.
+- **what**: plain-language description of the issue. No gate IDs, no JIRA jargon, no engineering shorthand. A product owner reading this on a Notion comment should understand what is unclear and why.
+- **recommendation**: 1–3 concrete options the reader can pick from, not a generic "please clarify." If the answer is genuinely open-ended, list the most plausible candidate resolutions you considered, even if speculative.
+
+## Rules
+
+- Never write to JIRA. This skill only invokes `lisa-atlassian-access` with read-only operations (`read-ticket`, `search-issues`, `list-sites`); it never calls write operations (`write-ticket`, `transition`, `comment`, `link`).
+- Never auto-fix the spec. This skill reports gaps; callers decide what to do (block, ask the human, regenerate the spec).
+- Never silently skip a gate. If a gate genuinely doesn't apply, return `N/A` with the reason; never omit it.
+- The `what` and `recommendation` fields must be concrete and product-readable — the dry-run path turns each failure into a Notion comment, and the audience for those comments is the product team, not engineers. Vague guidance ("clarify this", "decide how to handle X") is useless; always give 1–3 candidate resolutions.
+- Never emit a category outside the fixed set. If a new gate doesn't fit, propose adding the category to the taxonomy in this skill rather than inventing one inline.
+- `product_relevant` is determined by the gate, not by the failure context. Do not flip it per-failure.

package/plugins/src/base/skills/lisa-jira-verify/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: lisa-jira-verify
+description: This skill should be used when verifying that a JIRA ticket meets organizational standards for epic relationships and description quality. It fetches the live ticket and delegates the gate checks to jira-validate-ticket so the bar matches what jira-write-ticket enforces pre-write.
+allowed-tools: ["Skill"]
+---
+
+# Verify JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa-atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Verify that the existing JIRA ticket `$ARGUMENTS` meets organizational standards. This skill is a thin post-write wrapper around `lisa-jira-validate-ticket`: it fetches the live ticket and asks `lisa-jira-validate-ticket` to run the gates against the fetched state.
+
+This indirection exists so the gate definitions live in exactly one place (`lisa-jira-validate-ticket`). When the bar changes, change it there — `lisa-jira-verify`, `lisa-jira-write-ticket` (Phase 5.5 pre-write), and `lisa-notion-to-tracker` (PRD dry-run) all pick it up.
+
+## Process
+
+1. Invoke `lisa-atlassian-access` via the Skill tool with `operation: list-sites` to confirm the configured site is reachable (the access skill enforces connection match against `.lisa.config.json`).
+2. Fetch the ticket via `lisa-atlassian-access` `operation: read-ticket key: $ARGUMENTS`. Pull issue type, summary, description, parent, links, labels, components, and any custom fields needed.
+3. Invoke `lisa-jira-validate-ticket` and pass the ticket key. The validator fetches its own copy if needed and runs every gate (Specification + Feasibility) against the live state.
+4. Surface the validator's report verbatim to the caller.
+
+## Output
+
+Pass through `lisa-jira-validate-ticket`'s structured output unchanged. Do not summarize or paraphrase — downstream callers (e.g. `lisa-jira-agent`'s pre-flight gate) parse the gate lines.
+
+## Notes
+
+- This skill is read-only. It never edits the ticket, posts comments, or changes status.
+- If a gate fails, the recommendation is part of the validator's report; surface it as-is.
+- Validation Journey checks (S11) historically required a parser script (`parse-plan.py`); the parser logic now lives inside `lisa-jira-validate-ticket` so this skill no longer shells out to it.

package/plugins/src/base/skills/lisa-jira-write-ticket/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: lisa-jira-write-ticket
+description: "Creates or updates a JIRA ticket following organizational best practices. Enforces description quality (coding assistant / developer / stakeholder sections), Gherkin acceptance criteria, epic parent relationship, explicit link discovery (blocks / is blocked by / relates to / duplicates / clones), remote links (PRs, Confluence, dashboards), labels, components, fix version, priority, story points, and Validation Journey. Rejects thin tickets — use this skill any time a ticket is created or significantly edited."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Write JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa-atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Create or update a JIRA ticket with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin tickets are rejected.
+
+Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
+
+## Phase 1 — Resolve Intent
+
+Determine from $ARGUMENTS and context whether this is a CREATE or UPDATE:
+
+- **CREATE**: no existing ticket key provided
+- **UPDATE**: ticket key provided — call `/jira-read-ticket <KEY>` first to load the full current state before editing. Never overwrite without reading.
+
+Resolve the active Atlassian site via `lisa-atlassian-access` `operation: list-sites` (the access skill enforces connection match against `.lisa.config.json`).
+
+## Phase 2 — Gather Required Inputs
+
+Required fields (stop and ask if missing — do not invent values):
+
+| Field | Required For | Notes |
+|-------|--------------|-------|
+| Project key | CREATE | Resolve from `.lisa.config.json` (`jira.project`); ask the human if not configured |
+| Issue type | CREATE | Story, Task, Bug, Epic, Spike, Sub-task, Improvement |
+| Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
+| Description | CREATE, UPDATE | Multi-section — see Phase 3 |
+| Epic parent | Non-bug, non-epic | Enforced by `lisa-jira-verify` |
+| Priority | CREATE | Default to project default if unstated |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 |
+| Validation Journey | Runtime-behavior changes | Delegate to `/jira-add-journey` |
+| Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only tickets. |
+| Sign-in account / credentials | Tickets that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description (Phase 3). Omit when sign-in is not required. |
+| Single-repo scope | Bug, Task, Sub-task, Improvement | These leaf work units MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
+
+Optional but recommended: assignee, components, fix versions, labels, sprint, story points, reporter.
+
+Issue-type validity and required custom fields are enforced by `lisa-jira-validate-ticket`'s F1 / F4 gates (which run via `lisa-atlassian-access` under the hood). If you need to inspect the metadata directly, request a new operation in `atlassian-access` rather than calling MCP / acli yourself.
+
+## Phase 3 — Description Quality
+
+The description MUST address three audiences. Reject and rewrite if any are missing.
+
+```text
+h2. Context / Business Value
+[Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
+ Link to the originating Slack thread, Notion doc, incident, or customer report.]
+
+h2. 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.]
+
+h2. Acceptance Criteria
+# Given <precondition>
+  When <action>
+  Then <observable outcome>
+# Given <precondition>
+  When <action>
+  Then <observable outcome>
+
+h2. Out of Scope
+[Explicit list of what this ticket does NOT cover. Forces scope discipline.]
+
+h2. Target Backend Environment
+[Required when the ticket changes runtime behavior. One of: dev / staging / prod.
+ This is the environment QA/product reported against and the backend the
+ implementer points their local stack at during verification before CI/CD.
+ Backend-only tickets state the deployed env they target. Skip section
+ entirely for doc-only, config-only, or type-only tickets.]
+
+h2. Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role to sign in as, where to get the credentials
+ (1Password item name, env var, seeded fixture), and any MFA/SSO notes.
+ Omit the section entirely when sign-in is not required — its absence
+ means "no sign-in needed for this ticket."]
+
+h2. Repository
+[Required for Bug / Task / Sub-task / Improvement. Name the single repo this ticket covers.
+If the work spans repos, this ticket type is wrong — split into per-repo
+Tasks/Subtasks under a parent Story or Epic. Epic / Spike / Story may
+list multiple repos.]
+
+h2. Validation Journey
+[Delegate to /jira-add-journey if the ticket changes runtime behavior.
+ Skip only for doc-only, config-only, or type-only tickets.]
+```
+
+Rules:
+- Every acceptance criterion uses Given/When/Then. No vague "should work" language.
+- Every criterion is independently verifiable (UI, API, data, or performance check).
+- If the ticket is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
+- If the ticket is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings).
+- If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials.
+
+## Phase 4 — Relationship Discovery (Mandatory)
+
+Before creating or updating, find candidate relationships. Do NOT skip — this is the step agents most often omit.
+
+### 4a. Epic Parent
+
+If the ticket is not a Bug and not an Epic, it MUST have an epic parent:
+
+1. If explicitly provided, use it.
+2. Otherwise search active epics:
+   ```jql
+   project = <PROJECT> AND issuetype = Epic AND statusCategory != Done
+   ```
+   via `lisa-atlassian-access` `operation: search-issues jql: "<query>"`. 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 ticket.
+
+### 4b. Related Tickets
+
+Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the ticket.
+
+**Search 1: local git history** (catches PRs/commits that touched the same area but were never linked to a ticket):
+
+```bash
+# Commits mentioning the keyword
+git log --all --oneline --grep="<keyword>"
+
+# Commits that touched the relevant paths
+git log --all --oneline -- <path-or-glob>
+
+# Recent activity in this area (last 90 days)
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling ticket worth linking.
+
+**Search 2: Jira JQL** (catches open and recently-closed tickets):
+
+```jql
+# Open tickets touching the same component
+project = <PROJECT> AND component = "<component>" AND statusCategory != Done
+
+# Open tickets with overlapping keywords
+project = <PROJECT> AND (summary ~ "<keyword>" OR description ~ "<keyword>") AND statusCategory != Done
+
+# Epic siblings
+"Epic Link" = <EPIC-KEY>
+
+# Recent tickets touching the same labels
+project = <PROJECT> AND labels in (<labels>) AND updated >= -30d
+
+# Recently closed tickets in the same area (catches duplicates of work just shipped)
+project = <PROJECT> AND component = "<component>" AND status = Done AND updated >= -30d
+```
+
+**Record the outcome.** Add a `## Relationship Search` subsection (or a comment if updating an existing ticket) listing the queries you ran and what they returned. If the searches yielded nothing, write that explicitly — "Searched git history for `<keywords>` and JQL for component=`X`, label=`Y`, epic siblings; no related work found." A ticket with zero links and no documented search is rejected.
+
+For each candidate, classify the relationship:
+
+| Link Type | When to Use |
+|-----------|-------------|
+| `blocks` | This ticket must ship before the linked ticket can proceed |
+| `is blocked by` | The linked ticket must ship before this one can proceed |
+| `relates to` | Shared context, no ordering constraint |
+| `duplicates` | This ticket already exists — close one as duplicate |
+| `clones` | This ticket was created from the linked one (e.g. per-repo copies) |
+
+### 4c. Remote Links
+
+Identify and attach:
+- GitHub PRs, branches, or commits related to this work
+- Confluence pages (design docs, RFCs, runbooks)
+- Dashboards (Grafana, Datadog, Sentry issue)
+- Incident tickets (PagerDuty, Statuspage)
+- **Source artifacts from the originating PRD / parent epic**: classify and inherit per the rules in `lisa-tracker-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). The short version: enumerate the parent epic's remote links and inherit the ones whose domain matches this ticket's scope (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 — attach it here.
+
+If the ticket was generated from a PRD (by `lisa-notion-to-tracker` or similar) and the parent epic has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
+
+### 4d. Source Precedence (must appear on the ticket)
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa-tracker-source-artifacts` §3 and §4. When a ticket carries both design artifacts and a description, record the precedence explicitly in the ticket description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts. Cross-axis conflicts go under `## Open Questions` as BLOCKER items.
+
+For UI-touching tickets, include the existing-component reuse expectation per `lisa-tracker-source-artifacts` §7.
+
+### 4e. Live Product Walkthrough Findings (UI-touching tickets)
+
+If the ticket modifies an existing user-facing surface, a `lisa-product-walkthrough` should already have been run upstream (by `lisa-notion-to-tracker` Phase 2b or `lisa-jira-create`). Inherit its findings under a `## Current Product` subsection in the ticket description so the implementer sees what's shipped today before changing it. If the upstream skill skipped the walkthrough but this ticket clearly modifies an existing surface, invoke `lisa-product-walkthrough` here before proceeding.
+
+Use Jira's web UI or `lisa-atlassian-access` `operation: write-ticket` (UPDATE form) to set the `Development` field / remote links where supported.
+
+## Phase 5 — Set Metadata
+
+Before create/update, verify each field is populated where applicable:
+
+- Labels: include at minimum one triage label if relevant (e.g. `claude-triaged-{repo}` is added later by triage, not here)
+- Components: map from the modules the work touches
+- Fix Version: set if the team uses versioned releases
+- Priority: explicit — no "unset"
+- Story points: estimate for Story/Task/Bug, skip for Epic/Spike
+- Sprint: only if actively sprinting this work
+- Assignee: leave unset if unknown rather than auto-assigning
+
+### Build-ready control input (`build_ready`)
+
+`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit is promoted to the build-ready role on create. It never overrides `leaf-only-lifecycle` — a container is never promoted regardless of `build_ready`. Unlike the label-based trackers, JIRA tickets are **already created not-ready** (in the project's default initial status, e.g. `TODO`/`Backlog`); the build-ready role is the configured `ready` status (`jira.workflow.ready`, default `Ready`), reached by an explicit transition.
+
+- **Omitted** or **`build_ready: false`** → current behavior: leave the ticket in the project's default created status. No transition. A human (or `build_ready: true`) promotes it to the `ready` status later.
+- **`build_ready: true`** → after create, transition the **leaf** to the resolved `ready` role so `lisa-intake` / `lisa-jira-build-intake` auto-picks it up (see Phase 6 CREATE step). Resolve the role name with the standard pattern (`.jira.workflow.ready` // `Ready`, local overrides global). Best-effort: if the transition is unreachable, record it and leave the ticket in its default status rather than failing the write.
+
+## Phase 5.5 — Validate (Pre-write Gate)
+
+Before any write, invoke `lisa-jira-validate-ticket` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa-jira-validate-ticket` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
+
+The validator is the **single source of truth** for what makes a valid ticket. The same gates are used by `lisa-notion-to-tracker` dry-run, by `lisa-jira-verify` post-write, and here. Do not re-implement gate logic in this skill — if a gate needs to change, change `lisa-jira-validate-ticket` so every caller benefits.
+
+If the validator reports `FAIL`:
+- Surface the failure list and the per-gate remediation to the user.
+- Do NOT proceed to Phase 6. Fix the spec (or stop and ask the human) and re-run validation.
+- Never invoke `lisa-atlassian-access` with `operation: write-ticket` while the validator's verdict is FAIL.
+
+If the validator reports `PASS`, continue to Phase 6.
+
+## Phase 6 — Create or Update
+
+Before calling `lisa-atlassian-access`, keep the description in Lisa's normal Markdown/wiki-heading authoring shape; the access layer owns conversion through `scripts/markdown-to-adf.mjs` and writes ADF to JIRA. This is required because acli stores raw Markdown/wiki text as one literal paragraph when no ADF object is provided. Post-write verification must confirm the live description contains ADF `heading` nodes for the required sections, not literal `##` / `h2.` text in a paragraph.
+
+### CREATE
+
+1. Invoke `lisa-atlassian-access` via the Skill tool with `operation: write-ticket payload: {...}` containing all Phase 2/3/5 fields and the epic parent from Phase 4a (CREATE form — no existing key).
+2. Capture the returned ticket key.
+3. For each relationship from Phase 4b, invoke `lisa-atlassian-access` with `operation: link from: <K1> to: <K2> type: "<link-type>"`. Use the exact link-type names supported by the project; surface errors if an unknown type is passed.
+4. Attach remote links from Phase 4c (via `lisa-atlassian-access` `operation: write-ticket` UPDATE form or whatever remote-link operation is dispatched).
+5. If the ticket changes runtime behavior, invoke the `lisa-jira-add-journey` skill to append the Validation Journey section.
+6. **Build-ready promotion (only when `build_ready: true` and the ticket is a leaf work unit):** transition the new ticket to the resolved `ready` status via `lisa-atlassian-access` `operation: transition key: <K> to: "<ready-status>"` (resolve `<ready-status>` as `.jira.workflow.ready` // `Ready`, local overrides global). Skip this step entirely when `build_ready` is omitted or `false`, or for any container. If the transition is unreachable, record it and leave the ticket in its default status — do not fail the write.
+
+### UPDATE
+
+1. Invoke `lisa-atlassian-access` with `operation: write-ticket payload: {key: <K>, ...fields-being-changed}`. Do NOT resend fields that weren't in the change set — it blows away history.
+2. Add new relationships via `lisa-atlassian-access` `operation: link from: <K1> to: <K2> type: "<link-type>"`. Existing links are not touched unless explicitly removed.
+3. If description changes, preserve sections you are not editing. Re-read via `/jira-read-ticket` first, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `lisa-usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
+
+## Phase 7 — Verify
+
+Call the `lisa-jira-verify` skill on the resulting ticket. `lisa-jira-verify` fetches the live ticket and runs `lisa-jira-validate-ticket` against it — same gates as Phase 5.5, but applied to what JIRA actually stored (catches anything dropped or reformatted on write, including Markdown/wiki descriptions that degraded into one literal text paragraph instead of ADF heading nodes). If it reports failures, fix them before returning. Do not report success on a ticket that fails verify.
+
+## Phase 8 — Announce
+
+Post a creation comment via `lisa-atlassian-access` `operation: comment key: <K> body: "..."` with:
+- `[{repo}]` prefix if the ticket is repo-scoped
+- Who the ticket is assigned to (if known)
+- The relationships that were set (`blocks`, `is blocked by`, `relates to`) with links
+- Any remote PRs attached
+
+Skip this step only on UPDATE when no material change was made.
+
+## Rules
+
+- Never create a non-bug ticket without an epic parent.
+- Never skip relationship discovery — both the git history search AND the JQL search must run, and their outcomes must be recorded on the ticket. "None found" is acceptable only when it's documented.
+- Never create a Bug, Task, Sub-task, or Improvement that spans multiple repos. Split it before creating.
+- Never include a runtime-behavior ticket without a target backend environment, and never include an authenticated-surface ticket without sign-in credentials in the description.
+- Never invent custom field values. If the project requires a field you don't have, stop and ask.
+- Never overwrite a description without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
+- All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa-jira-create`) should delegate here rather than invoking `lisa-atlassian-access` write operations directly.
+- The gate logic (what makes a valid ticket) lives in `lisa-jira-validate-ticket`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa-jira-verify` post-write). When a gate needs to change, change it in `lisa-jira-validate-ticket` — every caller (write path, dry-run path, post-write verify) picks it up automatically.