@codyswann/lisa 1.82.2 → 1.83.0

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

@@ -0,0 +1,178 @@
+---
+name: 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", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__createJiraIssue", "mcp__atlassian__editJiraIssue", "mcp__atlassian__createIssueLink", "mcp__atlassian__getIssueLinkTypes", "mcp__atlassian__addCommentToJiraIssue", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Write JIRA Ticket: $ARGUMENTS
+
+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 cloud ID via `mcp__atlassian__getAccessibleAtlassianResources`.
+
+## Phase 2 — Gather Required Inputs
+
+Required fields (stop and ask if missing — do not invent values):
+
+| Field | Required For | Notes |
+|-------|--------------|-------|
+| Project key | CREATE | Call `getVisibleJiraProjects` if unknown |
+| Issue type | CREATE | Story, Task, Bug, Epic, Spike, 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 `jira-verify` |
+| Priority | CREATE | Default to project default if unstated |
+| Acceptance criteria | Story, Task, Bug, Improvement | Gherkin — see Phase 3 |
+| Validation Journey | Runtime-behavior changes | Delegate to `/jira-add-journey` |
+
+Optional but recommended: assignee, components, fix versions, labels, sprint, story points, reporter.
+
+Use `mcp__atlassian__getJiraProjectIssueTypesMetadata` to verify the issue type exists in the project and discover required custom fields.
+
+## 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. 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).
+
+## 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 `mcp__atlassian__searchJiraIssuesUsingJql`. 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
+
+Run targeted JQL searches to surface candidate links. Present candidates to the human (or record them on the ticket as a comment) before skipping. Suggested searches:
+
+```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
+```
+
+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)
+
+Use Jira's web UI or `mcp__atlassian__editJiraIssue` 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
+
+## Phase 6 — Create or Update
+
+### CREATE
+
+1. Call `mcp__atlassian__createJiraIssue` with all Phase 2/3/5 fields and the epic parent from Phase 4a.
+2. Capture the returned ticket key.
+3. For each relationship from Phase 4b, call `mcp__atlassian__createIssueLink` with the correct link type (verify names via `mcp__atlassian__getIssueLinkTypes` if unsure).
+4. Attach remote links from Phase 4c.
+5. If the ticket changes runtime behavior, invoke the `jira-add-journey` skill to append the Validation Journey section.
+
+### UPDATE
+
+1. Call `mcp__atlassian__editJiraIssue` with only the fields being changed. Do NOT resend fields that weren't in the change set — it blows away history.
+2. Add new relationships via `mcp__atlassian__createIssueLink`. 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.
+
+## Phase 7 — Verify
+
+Call the `jira-verify` skill on the resulting ticket. 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 `mcp__atlassian__addCommentToJiraIssue` 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 — record "none found" explicitly if the search returned nothing.
+- 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.
+- All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `jira-create`) should delegate here rather than calling the MCP write tools directly.

package/plugins/src/base/skills/spec-conformance/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: spec-conformance
+description: "Verifies that shipped work matches its spec section-by-section — acceptance criteria, Out of Scope, Technical Approach, Validation Journey assertions, and any explicit deliverables. Builds a coverage matrix mapping each requirement to evidence, flags scope creep separately from misses, and produces a verdict (CONFORMS / PARTIAL / DIVERGES). Runs during the verification phase alongside empirical system verification."
+allowed-tools: ["Read", "Glob", "Grep", "Bash", "Skill", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Spec Conformance: $ARGUMENTS
+
+Compare shipped work against its spec section-by-section. This is the "accountant lens" — did the work ship exactly what was written, nothing more, nothing less? It is NOT UX review (that's `product-specialist`) and it is NOT empirical system verification (that's `verification-specialist`). Run it alongside those, not instead of them.
+
+## Phase 1 — Resolve Spec Source
+
+Determine the source of truth for this work. Check in this order:
+
+1. **Explicit spec argument** — plan file path (e.g. `.claude/plans/<name>.md`), JIRA key (e.g. `PROJ-123`), Linear key, GitHub issue URL, or PRD path passed as `$ARGUMENTS`.
+2. **Linked JIRA ticket** — if the current branch or PR body references a JIRA key, use it.
+3. **PR body** — if the PR description contains a "Spec" or "Ticket" link, follow it.
+4. **Plan file on disk** — check `.claude/plans/` for an active plan matching the branch name.
+
+If none of the above resolves, stop. Do not guess what the spec was. Report: "No spec source found — pass a plan file, ticket key, or PR URL."
+
+Based on the source, load the full spec:
+
+| Source | How to Load |
+|--------|-------------|
+| Plan file (`.md`) | `Read` the file |
+| JIRA key | Invoke `/jira-read-ticket <KEY>` to get the full context bundle (primary ticket + epic + linked tickets) |
+| Linear key | Fetch via Linear MCP if available; else `Bash` with Linear CLI; else report "Linear reader unavailable" |
+| GitHub issue | `gh issue view <number> --json title,body,comments,labels,milestone` |
+| PRD | `Read` the file or fetch via Notion MCP if it's a Notion URL |
+
+## Phase 2 — Extract Requirements
+
+Parse the spec into a structured requirement list. Do NOT skip sections — every requirement becomes a row in the coverage matrix.
+
+Sections to extract:
+
+| Section | What to Extract | Classification |
+|---------|-----------------|----------------|
+| Acceptance Criteria | Each Gherkin scenario or bullet | `acceptance` |
+| Out of Scope | Each excluded item | `excluded` (flags scope creep) |
+| Technical Approach | Each concrete implementation commitment (not narrative) | `technical` |
+| Validation Journey Assertions | Each `Assertion:` bullet | `assertion` |
+| Deliverables | Each explicit deliverable (migration, doc, endpoint, script) | `deliverable` |
+| Plan file tasks | Each task marked complete in the plan | `task` |
+| Linked blocker resolutions | Each `is blocked by` that required work in this ticket | `blocker` |
+
+If an acceptance criterion is not in Gherkin, still extract it as a requirement — but flag it as `LOW_SPECIFICITY` so the verdict downgrades.
+Downgrade rule: if any `LOW_SPECIFICITY` requirement exists, the maximum possible verdict is `PARTIAL` unless the spec is tightened and re-evaluated.
+
+Skip narrative prose (Context / Business Value) — it isn't directly verifiable. Reference it only when explaining a miss.
+
+## Phase 3 — Inspect Shipped Work
+
+Gather evidence of what was actually shipped:
+
+1. **Diff scope** — the commits on the current branch vs. the default branch:
+   ```bash
+   BASE_BRANCH="$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')"
+   git log "${BASE_BRANCH}"..HEAD --oneline
+   git diff "${BASE_BRANCH}"...HEAD --stat
+   ```
+2. **File-level changes** — per-file diff for each changed file:
+   ```bash
+   git diff "${BASE_BRANCH}"...HEAD -- <file>
+   ```
+3. **Test coverage** — which tests were added/changed for the requirements:
+   ```bash
+   git diff "${BASE_BRANCH}"...HEAD -- '**/*.test.*' '**/*.spec.*'
+   ```
+4. **Empirical evidence** — output of `verification-specialist` if available (proof artifacts, API captures, UI screenshots, DB queries). If that report isn't in context, ask the caller for it before proceeding — do not substitute reading code for running the system.
+5. **PR description** — `gh pr view --json title,body,files` if a PR exists.
+6. **Deployed state** — if the verification phase already hit a deployed environment, use those captures.
+
+Do NOT run the system yourself — that's the verification-specialist's job. Your job is to map their evidence to the spec.
+
+## Phase 4 — Build Coverage Matrix
+
+For every requirement extracted in Phase 2, produce one row:
+
+| Column | Value |
+|--------|-------|
+| Requirement ID | Stable identifier (e.g. `AC-1`, `OOS-2`, `ASSERT-3`) |
+| Classification | `acceptance` / `excluded` / `technical` / `assertion` / `deliverable` / `task` / `blocker` |
+| Requirement Text | Verbatim from spec |
+| Evidence | Specific pointer — file:line, test name, verification report section, PR file, screenshot name |
+| Status | `MATCH` / `PARTIAL` / `MISSING` / `SCOPE_CREEP_VIOLATION` |
+| Notes | One line — why partial, what's missing, or where evidence is thin |
+
+### Status definitions
+
+- **`MATCH`** — requirement is implemented AND there is empirical evidence it works (test + verification report).
+- **`PARTIAL`** — implementation exists but evidence is incomplete (e.g. code present, no test; or test present, no run-time verification).
+- **`MISSING`** — requirement has no corresponding implementation OR no evidence at all.
+- **`SCOPE_CREEP_VIOLATION`** — used for `excluded` classification only. An Out-of-Scope item appears to have been shipped anyway. This is a different failure than a miss — it means the agent exceeded the spec.
+
+### Scope creep detection
+
+Separately from the matrix, scan the diff for work NOT traceable to any requirement. For each such change:
+
+- Identify the file/module
+- Summarize the change in one line
+- Classify as `UNTRACEABLE_CHANGE` (not necessarily wrong — refactors often land here — but MUST be surfaced)
+
+Untraceable changes are not automatic failures. They become findings the human reviews.
+
+## Phase 5 — Verdict
+
+Produce exactly one verdict:
+
+- **`CONFORMS`** — every requirement is `MATCH`. No `SCOPE_CREEP_VIOLATION`. Untraceable changes, if any, are clearly refactors or test support.
+- **`PARTIAL`** — some requirements are `PARTIAL` but none are `MISSING` or `SCOPE_CREEP_VIOLATION`. Work is mostly there but evidence is thin.
+- **`DIVERGES`** — at least one requirement is `MISSING`, OR at least one `SCOPE_CREEP_VIOLATION` exists, OR there are substantive untraceable changes that materially alter behavior.
+
+A verdict of `PARTIAL` or `DIVERGES` blocks task completion. The caller must resolve the gaps (implement the miss, remove the creep, add the missing evidence) before re-running.
+
+## Phase 6 — Output
+
+Structure the report so it can be pasted into a PR comment or JIRA ticket:
+
+```text
+## Spec Conformance Report
+
+**Spec source:** <plan file / JIRA key / Linear / GitHub issue / PRD>
+**Shipped scope:** <N commits, M files, K tests on branch <branch> vs <default-branch>>
+
+### Coverage Matrix
+
+| ID | Class | Requirement | Evidence | Status | Notes |
+|----|-------|-------------|----------|--------|-------|
+| AC-1 | acceptance | [text] | [pointer] | MATCH | |
+| AC-2 | acceptance | [text] | — | MISSING | No corresponding code or test |
+| OOS-1 | excluded | [text] | src/foo.ts:42 | SCOPE_CREEP_VIOLATION | Added anyway |
+| ASSERT-1 | assertion | [text] | verification-report §2 | PARTIAL | Asserted in code, not run in verification |
+
+### Untraceable Changes
+- src/utils/helpers.ts — extracted shared regex constant (refactor, no behavior change)
+- src/auth/session.ts — added retry logic (NOT IN SPEC — verify intentional)
+
+### Verdict: CONFORMS | PARTIAL | DIVERGES
+
+**Matches:** N/Total
+**Partial:** N
+**Missing:** N
+**Scope creep violations:** N
+**Untraceable changes flagged for review:** N
+
+### Required Actions (if PARTIAL or DIVERGES)
+1. [specific action — implement X, remove Y, add test for Z, capture evidence for W]
+2. ...
+```
+
+## Rules
+
+- Never substitute "I read the code and it looks right" for empirical evidence. If verification-specialist hasn't run yet, request its report before producing a verdict.
+- Never mark a requirement `MATCH` based on the presence of code alone — evidence means test + runtime observation.
+- Always surface scope creep separately from misses. They are distinct failures.
+- Always surface untraceable changes — even benign refactors — so the human can confirm intent.
+- The Out of Scope section is load-bearing. If the spec has one, every item must appear in the matrix as `excluded`.
+- If the spec has no acceptance criteria, flag the spec itself as inadequate before running the matrix. The verdict is `DIVERGES` for spec inadequacy until criteria are added.
+- Do not invent requirements the spec didn't state. If the shipped work does something reasonable but unspecified, it becomes an untraceable change, not a match.

package/plugins/src/base/skills/ticket-triage/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: ["Read", "Glob", "Grep", "Bash"]
 
 # Ticket Triage: $ARGUMENTS
 
-Perform analytical triage on the JIRA ticket. The caller has fetched the ticket details (summary, description, acceptance criteria, labels, status, comments) and provided them in context.
+Perform analytical triage on the JIRA ticket. The caller MUST have run `jira-read-ticket` first and provided the resulting context bundle — which includes the primary ticket, all linked tickets (blocks / is blocked by / relates to / duplicates), epic parent, epic siblings, subtasks, and remote PR state. Do not triage from a bare ticket summary — if the bundle is missing link or epic context, stop and instruct the caller to run `/jira-read-ticket` first.
 
 Repository name for scoped labels and comment headers: determine via `basename $(git rev-parse --show-toplevel)`.
 
@@ -23,6 +23,18 @@ If NO relevant code is found in this repo:
 
 If relevant code IS found, proceed to Phase 2.
 
+## Phase 1.5 -- Relationship & Epic Awareness
+
+From the context bundle, evaluate relationships before analyzing this ticket in isolation:
+
+- **Open blockers (`is blocked by`)**: if any blocker is not `Done` or its linked PR is not merged, raise an ambiguity: "Blocker {KEY} is not shipped — work cannot meaningfully start." This is an automatic `BLOCKED` verdict unless the human confirms the blocker state is acceptable.
+- **Epic siblings in progress**: if a sibling under the same epic is `In Progress` / `In Review` with a different assignee and overlapping scope, raise it as an edge case in Phase 4 ("Duplicate-work risk with {KEY}").
+- **`duplicates` / `is duplicated by` links**: if this ticket is a duplicate of an open ticket, verdict is `BLOCKED` with the recommendation to close as duplicate rather than implement.
+- **`relates to` links with shipped PRs**: flag the PRs in the verification methodology (Phase 5) as prior art worth reviewing before writing new code.
+
+Do not re-fetch tickets — the bundle already has the context.
+If Phase 1.5 finds an automatic blocker condition (`is blocked by` not shipped, or duplicate-of-open), emit `BLOCKED` immediately and skip to Phase 6 output formatting.
+
 ## Phase 2 -- Cross-Repo Awareness
 
 Parse the ticket's existing comments for triage headers from OTHER repositories. Look for patterns like:
@@ -111,7 +123,7 @@ Every verification method must be specific enough that an automated agent could
 Evaluate the findings and produce exactly one verdict:
 
 - **`NOT_RELEVANT`** -- No relevant code was found in this repository (Phase 1). The caller should add the triage label and skip implementation in this repo.
-- **`BLOCKED`** -- Ambiguities were found in Phase 3. Work MUST NOT proceed until the ambiguities are resolved by a human. The caller should post findings, add the triage label, and STOP.
+- **`BLOCKED`** -- Blocking conditions were found in Phase 1.5 (open blockers, duplicate-of-open) and/or ambiguities were found in Phase 3. Work MUST NOT proceed until resolved by a human. The caller should post findings, add the triage label, and STOP.
 - **`PASSED_WITH_FINDINGS`** -- No ambiguities, but edge cases or verification findings were identified. Work can proceed. The caller should post findings and add the triage label.
 - **`PASSED`** -- No ambiguities, edge cases, or verification gaps found. Work can proceed. The caller should add the triage label.
 

package/plugins/src/base/skills/verification-lifecycle/SKILL.md

@@ -42,9 +42,23 @@ A verification plan that only lists `bun run test`, `bun run typecheck`, or `bun
 
 After implementation, run the verification plan. Execute each verification type in order.
 
-### 7. Loop
+### 7. Spec Conformance
 
-If any verification fails, fix the issue and re-verify. Do not declare done until all required types pass. If a verification is stuck after 3 attempts, escalate.
+After empirical verification produces evidence, run spec conformance as a separate, mandatory step. Invoke the `spec-conformance` skill (or delegate to the `spec-conformance-specialist` agent) with the spec source — plan file, JIRA/Linear/GitHub key, or PRD.
+
+Spec conformance answers a question empirical verification does NOT: does the shipped work match what was asked, section-by-section? It consumes the empirical evidence from step 6 and builds a coverage matrix over every requirement (acceptance criteria, Out of Scope, technical commitments, Validation Journey assertions, deliverables).
+
+Required outputs:
+- Coverage matrix with one row per requirement
+- Scope creep findings (Out-of-Scope violations, surfaced separately from misses)
+- Untraceable change findings (diff not traceable to any requirement)
+- Verdict: `CONFORMS`, `PARTIAL`, or `DIVERGES`
+
+`PARTIAL` or `DIVERGES` blocks completion. Fix the gaps (implement the miss, remove the creep, capture the missing evidence) and re-run both empirical verification AND spec conformance. Never skip this step — it catches failures that empirical verification by itself does not, such as a feature that works but wasn't asked for, or a spec item that was quietly dropped.
+
+### 8. Loop
+
+If any verification or spec-conformance check fails, fix the issue and re-verify. Do not declare done until all required types pass AND the spec-conformance verdict is `CONFORMS`. If a verification or conformance check is stuck after 3 attempts, escalate.
 
 ---
 
@@ -180,8 +194,9 @@ Agents must follow this sequence unless explicitly instructed otherwise:
 8. Implement the change.
 9. Execute verification plan — run the actual system and observe results.
 10. Collect proof artifacts.
-11. Summarize what changed, what was verified, and remaining risk.
-12. Label the result with a verification level.
+11. Run spec conformance — build coverage matrix against the spec source (plan/ticket/issue), flag scope creep and untraceable changes, produce verdict.
+12. Summarize what changed, what was verified, conformance verdict, and remaining risk.
+13. Label the result with a verification level.
 
 ---
 
@@ -290,9 +305,10 @@ A task is done only when:
 
 - End user is identified
 - All applicable verification types are classified and executed
-- Verification lifecycle is completed (classify, check tooling, plan, execute, loop)
+- Verification lifecycle is completed (classify, check tooling, plan, execute, spec conformance, loop)
 - Required verification surfaces and tooling surfaces are used or explicitly unavailable
 - Proof artifacts are captured
+- Spec conformance verdict is `CONFORMS` (not `PARTIAL`, not `DIVERGES`)
 - Verification level is declared
 - Risks and gaps are documented