@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/skills/lisa-rework-triage/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: lisa-rework-triage
+description: "Rework detection and agent-failure classification. When a claimed ticket turns out to be rework — previously implemented work bounced back from QA/staging — this skill detects it, classifies WHY the previous agent attempt failed (decomposition infidelity, PRD defect, missing tool access, implementation defect, environment/data, verification gap), posts a structured triage comment, and routes each cause to its hardening destination — including upstream Lisa issues so the harness itself gets fixed and the same mistake structurally cannot repeat. Vendor-neutral: consumes the lisa-tracker-read context bundle; invoked automatically by lisa-ticket-triage Phase 2.5 and runnable standalone."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Rework Triage: $ARGUMENTS
+
+Classify why the previous attempt failed and repair the actual cause. Apply `do-it-now`'s **Worth doing** guidance before proposing additional hardening. Fixing the defect and its relevant regression test can be sufficient; a failure does not automatically justify another rule, hook, or upstream ticket.
+
+The caller MUST have run `lisa-tracker-read` first and provided the context bundle (all
+comments chronological, linked PRs with review state, issue links, parent epic). Do not
+classify from a bare summary — evidence-free classification is worse than none.
+
+On runtimes without the rule tree (Antigravity), read **Worth doing** in `lisa-track` for the same value and decline policy.
+
+## Phase 1 — Rework detection
+
+A ticket is **rework** when it was previously implemented by this lifecycle and has returned
+to a build-ready state. Evaluate these signals in order; the first confirmed signal suffices.
+If none confirm, output `## Verdict: NOT_REWORK` and stop — this skill takes no action on
+first-attempt work.
+
+1. **Status history shows a post-implementation regression transition.** The ticket's
+   changelog contains a transition from a post-build state (the configured `claimed`,
+   any configured `done.*` environment state, or a review state) back to the configured
+   `ready` state.
+   - JIRA: fetch the changelog via the `lisa-atlassian-access` REST substrate —
+     `GET /rest/api/3/issue/<KEY>/changelog` — and scan `items[].field == "status"` entries.
+   - GitHub: `gh issue view <n> --json timelineItems` (or the timeline API) — scan for the
+     `$DONE`/environment label being removed and `$READY` re-added after a linked PR merged.
+   - Linear: the Issue history relation — scan state changes from a completed/started state
+     back to the ready-labeled state.
+2. **Merged linked PR + build-ready again.** The bundle shows at least one linked PR that is
+   `MERGED`, while the ticket currently carries the build-ready role. First-attempt tickets
+   never have merged PRs.
+3. **Prior lifecycle claim marker.** The comments contain a prior implementation-cycle
+   marker for THIS ticket: a `[claude-build-intake]` claim comment, or a build-evidence
+   comment posted by `lisa-tracker-evidence` (`[lisa-evidence]` / the vendor evidence
+   header). Only markers proving a prior *implementation* attempt qualify —
+   `[lisa-rework-triage]` comments and other unrelated `[lisa-*]` annotations never do.
+4. **Explicit rework marker.** A `rework` or `regression` label applied by QA or the verify
+   lifecycle, or a **live** QA-failure signal.
+
+   The QA-failure signal is transient, so its bare presence is not the signal — its
+   liveness is. Ask the resolver, never the label list:
+
+   ```bash
+   RESOLVER="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-plugins/lisa}}/scripts/qa-signal-lifecycle.mjs"
+   node "$RESOLVER" --vendor "<jira|linear|github>" --item bundle.json
+   # bundle.json: { "labels": [...], "comments": [<bodies, oldest first>], "role": "<current>" }
+   ```
+
+   Branch on `outcome`, never on the label being there. The resolver's separate
+   `action` field is `keep` / `clear` / `none`; it is not the liveness verdict:
+
+   | `outcome` | Meaning | What triage does |
+   |---|---|---|
+   | `live` | the failure is unresolved | signal 4 fires — this is rework |
+   | `stale` | a later QA pass, or the certified/terminal role, voided it | signal 4 does **not** fire; **remove the label** (same tracker surface that applied it) and note the repair in the triage comment. Keep evaluating signals 1–3 |
+   | `absent` | no signal | signal 4 does not fire |
+   | `unchecked` | a declared void condition has no predicate | treat as `live` and surface it — a control nothing can evaluate is a defect to report, not an exemption |
+
+   Clearing a stale signal here is the repair path for items labelled before the signal had
+   an inverse; without it that backlog never drains. The `[lisa-qa-fail]` comments are the
+   history and are never touched — a stale signal removed still leaves the failure fully
+   readable, and signal 3 still reads those comments.
+
+   `rework` and `regression` are matched on presence as before. Whether they have the same
+   shape is **unverified** and not claimed here.
+
+Record which signal fired — it is part of the evidence trail.
+
+## Phase 2 — Failure-cause classification
+
+Classify the failed attempt into **exactly one primary cause**. Every classification must
+cite concrete evidence from the bundle, the codebase, or the PRD lineage — a cause without
+evidence is `UNCLASSIFIED`, which is itself a surfaced outcome, never a silent default.
+
+| Cause | Definition | Required evidence |
+|-------|------------|-------------------|
+| `decomposition-infidelity` | The ticket misrepresents the PRD requirement it implements — the agent built what the ticket said, but the ticket distorted the spec. | Resolve the ticket's requirement id(s) from the source PRD's `## Tickets` section (written by `lisa-prd-backlink` — each entry carries `requirements: ["R#"]` and the register maps R# to verbatim PRD text). Quote the PRD text vs. the ticket's AC and name the divergence. |
+| `prd-defect` | The ticket faithfully captured the PRD, but the PRD itself was wrong, ambiguous, or missing the failing case. | Quote the PRD requirement and the QA failure it does not cover or contradicts. |
+| `missing-tool-access` | The agent lacked a tool, credential, environment, or permission the work required, and worked around it blindly. | The prior cycle's comments/PR show the gap (skipped verification step, "could not access", missing env credentials, absent MCP tool) — cite the marker. |
+| `implementation-defect` | Spec and ticket were right; the agent's code was wrong. | The failing behavior contradicts an AC the ticket states correctly; cite the AC and the failure report. |
+| `environment-data` | The failure is caused by environment or data state (drift, missing fixtures, shared-state collision), not by the code under test. | The failure reproduces only in the affected environment, or the report references data absent from the environment's seed/fixtures. |
+| `verification-gap` | The code was wrong AND the verification lifecycle should have caught it — the codified regression test was missing, too weak, or asserted the wrong thing. | Name the verification/codify-verification artifact from the prior cycle that failed to catch this class of failure. Frequently a **secondary** cause alongside `implementation-defect`; record both, primary first. |
+
+Classification sources, in priority order: the QA failure report (comments), the prior
+cycle's evidence comment and PR review thread, the PRD requirement register via
+`lisa-prd-backlink` lineage, and the codebase itself (Glob/Grep the failing surface).
+
+## Phase 3 — Post the triage comment
+
+Post one structured comment on the ticket via the vendor comment surface (`lisa-atlassian-access
+operation: comment`, `gh issue comment`, or the Linear comment mutation):
+
+```text
+[lisa-rework-triage] Rework detected (signal: <signal>)
+Fingerprint: <ticket-key>|<last merged PR number, or none>|<primary cause>
+Primary cause: <cause>
+Secondary cause: <cause or none>
+Evidence: <2-4 lines citing the specific PRD text / AC / comment / PR review / environment fact>
+Hardening action: <what Phase 4 filed, with link — or "none required (implementation-defect)">
+```
+
+**Idempotency:** the fingerprint is the literal `Fingerprint:` line —
+`<ticket-key>|<last merged PR number>|<primary cause>`, with `none` as the PR component
+when detection fired on a claim marker or label and no merged PR exists. Before posting,
+scan existing comments for a `[lisa-rework-triage]` block whose `Fingerprint:` line
+matches — if present, skip posting and report `already-triaged`. One triage per bounce,
+never one per cycle re-entry.
+
+## Phase 4 — Route the cause to its hardening destination
+
+For each primary or secondary cause, first decide whether additional work clears
+`do-it-now`'s **Worth doing** bar. If not, report `Hardening action: none required`
+with a brief reason in the existing triage comment. Do not create a replacement
+learning or a human gate merely to retain the declined observation.
+
+The table gives destinations for accepted additional work. File through the proper write path — never raw
+ticket creation — so every hardening artifact passes the same quality gates as any other
+Lisa work item.
+
+| Primary cause | Destination | Action |
+|---------------|-------------|--------|
+| `decomposition-infidelity` | **Upstream Lisa issue** | The decomposition pipeline produced an unfaithful ticket and every gate passed it — that is a harness defect. File per "Filing upstream" below, citing the PRD text, the distorted ticket AC, and which gate should have caught it. |
+| `verification-gap` | **Upstream Lisa issue** | The verification lifecycle passed work it should have failed. File per "Filing upstream", citing the missed failure class and the weak/missing codified test. |
+| `missing-tool-access` | Project tracker | Create a provisioning ticket via `lisa-tracker-write` (`issue_type: Task`, labeled `type:tooling`) describing the missing tool/credential/environment and which flow needs it. Link it `blocks` the rework ticket. Pass `human_gate: "a human must grant the missing access"` per `ready-role-filing` — the factory cannot provision its own credentials, so this is a declared gate rather than an unclaimed filing. |
+| `environment-data` | Project tracker | Create an environment-hardening ticket via `lisa-tracker-write` citing the drift/fixture/shared-state evidence. Link `relates to` the rework ticket. Pass `build_ready: true` when the hardening is a code/fixture change the factory can make, or `human_gate: "<the shared-environment decision a human owns>"` when it is not — per `ready-role-filing`, never neither. |
+| `prd-defect` | Source PRD | Comment on the PRD (via the `lisa-prd-backlink` lineage) quoting the defective requirement and the QA failure; flag for product review. Do NOT silently edit the PRD — spec changes are a human gate. |
+| `implementation-defect` (no secondary) | None | Normal fix path; the classification comment is the record. Pass the pattern to the `learner` phase — repeated implementation defects of the same shape escalate to `verification-gap`. |
+
+**Secondary causes route too — when worthwhile.** A worthwhile secondary cause uses its row's
+destination in addition to the primary's: `implementation-defect` with a
+`verification-gap` secondary files the upstream Lisa issue per the `verification-gap`
+row — the code being wrong does not excuse the verification lifecycle for passing it.
+Deduplicate against the primary's filing (one upstream issue per failure class, not one
+per cause slot).
+| `UNCLASSIFIED` | Surface to human | Include in the triage comment and the caller's summary; a human decides. Never guess a cause to avoid this outcome. |
+
+### Filing upstream
+
+Upstream issues target the Lisa repository itself so the harness gets fixed for every
+project at once. Resolve the repo from `.lisa.config.json` `hardening.upstreamRepo`;
+default `CodySwannGT/lisa`.
+
+There are **two upstream lanes**, distinguished by what the filing proposes. Both share
+the same dedupe-marker and evidence-chain discipline below; only the label and one body
+section differ:
+
+| Lane | Label | When | Extra body section |
+|------|-------|------|--------------------|
+| Defect | `self-hardening` | A Lisa gate/skill/template did something wrong — a harness bug the kernel must fix. | none |
+| Contribution | `template-candidate` | A generalizable pattern discovered downstream that would benefit every host project — not a defect, a proposed improvement to Lisa's templates/rules/skills. | `## Proposed template change` |
+
+1. **Dedupe first.** Search open AND closed items and consult `rejection-detection`'s **Proposal rejection memory**, including legacy issues without markers. `gh issue list -R <upstream> --state all --search "<fingerprint terms>"`
+   — if an open issue already covers this failure class or pattern, comment the new
+   occurrence on it (evidence compounds; duplicates dilute) and link it instead of filing.
+2. **File with the same bar as any ticket:** a three-audience description (what failed or
+   improved for the operator, what the harness did or could do, what to change), the
+   public-safe evidence chain (PRD text → ticket AC → QA failure → gate that passed it; for
+   patterns, the occurrences proving generality). Invoke `lisa-github-write-issue` against
+   `<upstream>` using the existing public-safe attribution/projection procedure from
+   `upstream-to-lisa`. Pass `build_ready: true` unless an explicit `human_gate` was declared,
+   then pass that reason instead. Use label `self-hardening` for defects or `template-candidate`
+   for contributions. A `template-candidate` filing MUST include a
+   `## Proposed template change` section naming the Lisa template/rule/skill surface to
+   change (e.g. `typescript/package-lisa/package.lisa.json`, a `plugins/src/base` rule)
+   and the proposed content or diff sketch, so Lisa-side intake can triage it as a
+   contribution rather than a defect.
+3. **Close the loop.** Reference the upstream issue URL in the triage comment. The upstream
+   repo's own build intake implements it; the next kernel release ships the hardening (or
+   the generalized pattern) to every host project.
+
+## Verdict
+
+```text
+## Verdict: [NOT_REWORK | REWORK_CLASSIFIED | ALREADY_TRIAGED]
+
+**Signal:** [status-history | merged-pr | claim-marker | label | n/a]
+**Primary cause:** [cause | n/a]
+**Secondary cause:** [cause | none]
+**Hardening filed:** [upstream <url> | tracker <key> | prd-comment | none | pending-human]
+```
+
+The caller (ticket-triage Phase 2.5, or a standalone invocation) incorporates this into its
+own findings. `REWORK_CLASSIFIED` never blocks the fix — the rework ticket proceeds to
+implementation regardless; hardening runs alongside, not in front of, shipping the fix. The
+one exception: `missing-tool-access` with the gap still present should surface as a Phase 3
+ambiguity in the calling triage ("prior attempt lacked <tool>; it is still unavailable"),
+which blocks per the normal triage rules.
+
+## Rules
+
+- Never classify without evidence; `UNCLASSIFIED` beats a guess.
+- One primary cause. Record a secondary only when the evidence genuinely supports both.
+- Fire only on confirmed rework — first-attempt tickets exit at Phase 1 with `NOT_REWORK`.
+- All ticket/issue writes go through `lisa-tracker-write` or `gh` as specified — never
+  bypass the quality gates this loop exists to strengthen.
+- Noise discipline: one triage comment per bounce (fingerprinted), no upstream issue without
+  the dedupe search, and upstream issues describe failure *classes*, not single incidents.
+- Never key on a durable mark whose inverse you have not checked. A signal with no expiry
+  degrades toward meaning "this item has been around a while"
+  (`state-changes-without-inverses`), and a deterministic input that degrades is
+  deterministically wrong.

package/plugins/lisa-devin/skills/lisa-root-cause-analysis/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: lisa-root-cause-analysis
+description: "Prove what causes a defect: hypotheses written down before evidence is gathered, positive confirmation by execution rather than by surviving a disproof, a symptom-keyed technique menu including git bisect, and a declared stopping point that escalates an unresolved verdict instead of drifting."
+---
+
+# Root Cause Analysis
+
+Produce a proof, not an explanation. Every link in the chain rests on something observed — a log line, a stack frame, an exit code, a bisect verdict.
+
+## Confirm by executing, not by reasoning
+
+The characteristic failure of this work is a fluent wrong answer: a plausible story assembled from reading code and delivered with confidence. Reading is how a hypothesis is formed. Running something is how it is confirmed. **Do not report a cause you have not executed against.**
+
+## Surviving a disproof is not proof
+
+A candidate that no observation has killed is **still standing**, not confirmed. Elimination narrows the field; it does not establish a cause. Closing requires a **positive confirmation**: an execution whose output is what the cause predicts and would not be what it produces if the cause were something else.
+
+That leaves three honest verdicts, and the output has to be able to say each:
+
+- **confirmed** — a positive confirmation was executed and is recorded.
+- **inconclusive** — one candidate is standing, nothing killed it, nothing confirmed it. Say so; do not promote it.
+- **unresolved / blocked** — the investigation stopped before reaching a cause. See the stopping rule.
+
+Only *confirmed* justifies a fix. An inconclusive verdict can still be useful — it narrows the next attempt — but it must be labelled.
+
+## Write the hypotheses down first
+
+Before gathering evidence, list the candidate causes — two or three is normal — and beside each, the observation that would **kill** it. Then go looking for the killing observations rather than for support.
+
+A candidate you cannot state a disproof for is not a hypothesis; it is a hunch, and it will survive any amount of evidence. Keep the list updated as you work, and ship the eliminated candidates in the output: they are how a reader knows you looked.
+
+## Pick the technique from the symptom
+
+| What you know | Reach for |
+| --- | --- |
+| **It used to work**, and a good commit can be named | `git bisect` — preconditions below |
+| A stack trace or error location | Work backward from the throw; read the frames that carry the value, skip the plumbing |
+| Only that the result is wrong, no location | Instrument first. Reading code to localize an unlocalized defect is the slowest move available |
+| Intermittent | Loop it. Log timestamps and identity either side of async boundaries; look for overlap, staleness, out-of-order completion |
+| Works locally, fails deployed | Diff the environments — version, config, data, permissions, network — before touching code |
+| Wrong shape, missing field, unexpected null | Log the actual value at each transformation, not the type you expect |
+| Possibly a dependency | Pin the exact installed version; read its changelog and issues before blaming local code |
+
+### git bisect
+
+The highest-leverage move available for a regression, and consistently underused: it answers *which change* in log₂(n) steps instead of log₂(n) hours of reading. It needs three things and wastes time without them.
+
+1. **A known-good commit** — from the last release, the last green run, or the reporter's "it worked on…".
+2. **A deterministic, non-interactive check** that exits non-zero on the defect. The failing test from `reproduce-bug` usually is one.
+3. **A runnable checkout at every step.** Where a fresh checkout needs a dependency install or build before tests run, fold that into the bisect command. Otherwise every step fails for the wrong reason and the verdict is noise.
+
+```bash
+git bisect start <bad> <good>
+git bisect run <cmd>   # <cmd> must install/build if the checkout needs it
+```
+
+Read the blamed commit before believing it. Bisect names the change that *surfaced* the defect, which is not always the change that introduced it.
+
+## Find the logs the project already has
+
+Look for existing tooling before reaching for a raw CLI: `package.json` scripts, `scripts/*log*`, `scripts/*tail*`, AWS CLI wrappers, log-group names in `.env`. Project tooling already encodes the credentials, regions, and group names you would otherwise guess at.
+
+Where no wrapper exists:
+
+```bash
+aws logs describe-log-groups --query 'logGroups[].logGroupName' --output text
+aws logs tail "/aws/lambda/<name>" --follow --since 30m
+```
+
+If remote logs are unreachable, name the log group and the time window needed rather than proceeding without them.
+
+## Instrument surgically
+
+Add the fewest statements that decide between live hypotheses, and make each carry values rather than announce arrival. Guard the access — instrumentation that throws while reading its own subject tells you nothing about the defect.
+
+```typescript
+// Useless: proves a line ran.
+console.log("here", data);
+
+// Useful: decides a hypothesis, and survives the shape it is investigating.
+console.log("[DEBUG:issue-123] processOrder entry", {
+  orderId: order?.id,
+  status: order?.status,
+  itemCount: order?.items?.length ?? null,
+});
+```
+
+Highest-yield placements: function entry (called at all, with what), either side of a branch (which way, on what value), either side of an `await` (timing, staleness), around transformations (where the shape changes), and inside `catch` blocks (what is being swallowed).
+
+The `[DEBUG:<issue>]` prefix exists so cleanup is mechanical rather than remembered. Once the verdict is recorded, remove every one — keeping only logging that belongs in the product permanently — and verify across every source root the project has, not just one:
+
+```bash
+git grep -n "\[DEBUG:"
+```
+
+## Stop before you drift
+
+Declare a budget before starting: a number of instrumentation rounds, or a wall-clock box. Two signatures mean stop now rather than push on.
+
+- **Two consecutive hypotheses falsified with no new information gained.** Widening the search against the same evidence is not progress.
+- **The budget is spent.**
+
+Stopping is a legitimate outcome and not a silent one. Record the verdict as **unresolved / blocked** and escalate a decision-ready report: the symptom, the hypotheses tried and how each was killed, the evidence collected, and the single thing that would unblock the work — an access grant, a log group, a reproduction on the real path. A blocked investigation reported clearly is worth more than a confident guess, and costs the next agent far less.
+
+## Output
+
+`Cause` and `Fix` are required only for a **confirmed** verdict. For *inconclusive* or *unresolved*, record what is known and name the unblocker instead — an unresolved investigation must be representable without inventing a cause to fill the field.
+
+```text
+## Root Cause Analysis
+
+**Verdict:** confirmed | inconclusive | unresolved
+
+### Hypotheses
+| Candidate | Would be killed by | Status |
+|---|---|---|
+| ... | the observation that would disprove it | eliminated / standing / confirmed |
+
+### Evidence trail
+| Step | Location | Observed | Proves |
+|---|---|---|---|
+| 1 | file:line | log output, value, exit code | what this establishes |
+
+### Cause — confirmed verdicts only
+**Proximate:** file:line — the line that directly produces the symptom.
+**Root:** file:line — why that line behaves that way.
+**Confirmation:** the command run and its output, and why that output would differ
+  if the cause were something else. Not an argument.
+
+### Fix — confirmed verdicts only
+What changes and why, with file:line references. Anything that must not change.
+
+### Unblocker — inconclusive or unresolved verdicts
+The single thing that would let the next attempt proceed, and who can grant it.
+```