@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/skills/lisa-reproduce-bug/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: lisa-reproduce-bug
+description: "How to reproduce a bug reliably and on the real path — choosing a reproduction method from the symptom, distinguishing prerequisites from behaviour-substituting scaffolding, and reporting the observed failure rate instead of rounding it."
+---
+
+# Reproduce Bug
+
+A bug that cannot be reproduced cannot be verified as fixed. Root cause analysis does not begin until a reliable reproduction exists.
+
+## The reproduction must exercise the real path
+
+Left alone, an agent asked to demonstrate a defect will build the environment in which the defect appears — a stub, a fake, a fresh harness — and present that as the reproduction. It looks like proof and it is not: a fix that satisfies it may never touch the path the user is on.
+
+Two kinds of setup get confused here, and only one is a problem:
+
+- **Prerequisites** — state the real path genuinely needs: a seeded record, a logged-in user, a feature flag, a fixture recreating production-equivalent data. These are part of the reproduction. Removing them changes the precondition rather than testing anything, so do not remove them.
+- **Replacement scaffolding** — anything standing in for behaviour the real path would perform: a mocked service, a stubbed function, a fake clock, a bespoke harness that bypasses the normal entry point. This is what makes a reproduction suspect.
+
+So the reproduction states, explicitly:
+
+- **The entry point the user actually hits** — the route, endpoint, command, or interaction.
+- **Prerequisites**, listed as setup.
+- **Replacement scaffolding**, each item with the real behaviour it substitutes.
+- **Whether the failure survives with prerequisites in place and replacement scaffolding removed.** If it does not, this is a lead rather than a reproduction. Say so and keep going.
+
+If the real path is unreachable — no credentials, no environment, no data — that is a blocked reproduction. Report the missing access instead of substituting scaffolding and calling the bug reproduced.
+
+## Choose the method from the symptom
+
+| Symptom | Reach for |
+| --- | --- |
+| Wrong value, bad output, thrown error | Failing test at the narrowest layer that still crosses the real path |
+| Broken interface or journey | Browser or device driver against a running build (Playwright, Maestro) |
+| Service or API behaviour | Direct request to the running service — client script or `curl` |
+| Depends on particular data | Seeded fixture recreating that state, recorded as a prerequisite |
+| Intermittent or timing-shaped | Loop the trigger; capture timestamps around async boundaries |
+| Works locally, fails deployed | Do not chase it locally — reproduce against the environment that fails |
+
+**A failing test is the preferred form** wherever it can cross the real path: it runs in CI, it becomes the regression guard, and `codify-verification` expects it. A script is the fallback. Manual steps are the last resort and must carry their prerequisites.
+
+## When the work item names an existing test as the reproduction
+
+A work item may hand you the control instead of asking you to build one: *"`<existing test>` pins today's wrong behaviour; it must go red once this is fixed."* Treat that as a reproduction only once it is **reachable** — the `control-reachability` rule holds that a test whose fixture never exercises the changed path stays green for a reason unrelated to the change, so its green is uninterpretable and the item's stopping rule reads as "revert a correct fix".
+
+- **Before trusting it**, check the item for the `[CONTROL: <test-identifier> | reaches: <input-or-field>]` marker gate S20 requires, and confirm the named input is actually in the fixture. A named test with no stated reachability is an unvalidated control, not a reproduction.
+- **If it does not move when the change lands**, stop and establish why: the change had no effect (revisit the change), or the fixture never reached the changed path (fix or extend the control). Prove it by execution — a temporary `throw` in the changed block run under that one test, or coverage scoped to that test alone — never by reading the fixture and concluding it looks right.
+- **Never revert on an unexplained green.** Report the finding — which method you used and what it showed — the way any other reproduction result is reported.
+
+## Report the failure rate, do not round it
+
+Run the reproduction enough times to state a rate. A reproduction that fails half the time cannot prove a fix — one passing run afterwards means nothing at that rate. If the rate is too low to distinguish a fix from luck, say what would raise it: more iterations, a forced schedule, a narrowed trigger, a seeded clock.
+
+## When it will not reproduce
+
+The difference is nearly always one of: runtime version, configuration or feature flags, data state, credentials and permissions, network posture, or platform. Diff the two environments along those axes rather than guessing between them, and report which axes you compared and what you found. That comparison is the finding when the bug stays hidden.
+
+## Output
+
+```text
+## Reproduction
+
+**Entry point:** the route, command, or action the user hits
+**Command or steps:** exactly what to run
+**Actual:** what happens · **Expected:** what should happen
+**Prerequisites:** seeded data, auth state, flags the real path needs — or "none"
+**Replacement scaffolding:** each mock, stub, fake, or bespoke harness and the
+  real behaviour it substitutes — or "none"
+**Survives without replacement scaffolding:** yes / no — if no, this is a lead,
+  not a reproduction
+**Observed failure rate:** n failures in m runs
+**Form:** failing test `path` | script `path` | manual steps above
+**Environment:** runtime, platform, relevant dependency versions
+```
+
+Capture output whole — a truncated stack trace loses the line that mattered. But evidence carries whatever the system was holding, so **redact secrets, tokens, credentials, and personal data before a reproduction is handed on or attached to a work item**, and keep any unredacted capture only where the data class it contains is already permitted to live.

package/plugins/lisa-devin/skills/lisa-research/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: lisa-research
+description: "Research a problem space and create a PRD in the configured PRD source. Investigates the codebase, defines user flows, assesses technical feasibility, synthesizes the spec, then creates it in the source (Notion / Confluence / GitHub / Linear per .lisa.config.json `source`) via lisa-prd-source-write — there is no loose document artifact. Vendor-agnostic. Accepts an optional `prd_ready` flag (default false → the PRD is created in the `draft` role; true → created `ready` so lisa-intake auto-claims it) and an optional dedupe `marker`/`dedupe_key` (used when invoked by lisa-project-ideation) so re-runs reference the existing PRD instead of duplicating it."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Research
+
+Produce a PRD for the problem in `$ARGUMENTS`, then create it in the configured PRD source.
+
+## Inputs
+
+- The problem statement / feature idea (required) — free text, a feasibility card, or a URL.
+- `prd_ready` (optional, default `false`) — `false` creates the PRD in the source's `draft` role for
+  human review; `true` creates it in the `ready` role so `lisa-intake` (PRD side) auto-claims it.
+- `dedupe_key` / `marker` (optional) — a stable dedupe marker (e.g. supplied by
+  `lisa-project-ideation`) embedded in the created PRD so re-runs reference the existing PRD rather
+  than creating a duplicate.
+- `ideation_ledger_payload` (optional, required when invoked by `lisa-project-ideation`) — a
+  structured metadata object to forward unchanged to `lisa-prd-source-write`. It carries the
+  selected marker, automation id/path when available, persona names, persona evidence references,
+  rejected overlap candidates, repo identity, `prd_ready`, selected idea title/key, and expected
+  empirical verification artifact. When supplied, `reproposal_context` contains the dated decline,
+  new evidence, changed consequence, and the required machine token and human acknowledgment.
+  Include that token and acknowledgment verbatim in the synthesized PRD body before source routing,
+  so the justification survives even when the vendor's metadata renderer does not display this field.
+  Other metadata may inform the PRD body; forward the complete payload unchanged without renaming
+  or vendor-rendering its fields.
+
+## Orchestration: agent team
+
+You are "inside an agent team" only if you are yourself a spawned teammate or subagent — you were spawned into a team context, or your context names a team lead you report to. A lead/root session that has previously spawned subagents is still the lead and retains full authority to create this flow's team.
+
+If you are NOT inside an agent team by that definition, the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude Code >= 2.1.178: there is no `TeamCreate` tool; the team forms automatically when you spawn the first teammate with `Agent`. That first spawn should be the bounded specialist needed to start this flow. On older Claude Code that still exposes `TeamCreate`, the explicit team-create path is also acceptable.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
+
+Until the team is established, the first Codex teammate has been spawned, or the no-team fallback has been declared, do NOT call any of: `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. The initial Claude `Agent` spawn described above is the only pre-team exception because it establishes the team. Gathering context inline as the lead is the exact bypass path that produces ad-hoc work instead of a real team flow.
+
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+## Flow
+
+Execute the **Research** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gates, sub-flows, deliverables). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+## Output
+
+A PRD **created in the configured PRD source** (per the intent-routing rule's Research flow
+definition) structured as: problem statement, high-level solution description, links (if needed),
+user stories (each with its own functional/non-functional requirements and, only for stories with
+new UI/visual work, a design-file pointer), overall acceptance criteria, open questions, and the
+"Recommended Tooling for Plan Phase" section. Requirements MUST conform to the
+`prd-definition-of-ready` rule: identified atoms (`R1`, `R2`, …), one behavior each in an
+EARS-pattern shape, each with a measurable fit criterion, plus the non-functional checklist. For any
+story with frontend scope, its user-facing behavior MUST be expressed as — or in a shape directly
+convertible to — Given/When/Then scenarios, naming the platforms each behavior must hold on, per the
+`bdd-e2e-coverage` rule; narrative-only frontend behavior forces that shape to be invented later,
+inconsistently, by whoever picks up the ticket. Where a requirement introduces or changes
+**persistent state** — anything the system writes that outlives the process that wrote it, rows being
+only one kind — the PRD MUST name that state and the reset policy it is expected to take, per the
+`reset-seed-coverage` rule, so the classification is a stated requirement rather than something
+discovered when a leaked record breaks a suite; that rule also covers the non-row cases (identity
+objects, object storage, search indexes, queues, caches, derived views) a narrative spec routinely
+omits. Each scenario stub carries its originating requirement
+atom (`R1`, `R2`, …) even though the stable `@BDD-<DOMAIN>-<NNN>` ID is not minted until Plan or
+Implement — this is what lets a later stage's provenance tag, and `spec-conformance`'s traceability
+check, walk back from a shipped scenario to the PRD requirement it was written to satisfy, instead of
+accepting any scenario with a stable ID as proof of this requirement. The final
+flow step invokes `lisa-prd-source-write`, which creates the PRD in the configured `source` (Notion
+page in the PRD database, Confluence page under the lifecycle parent, GitHub issue, or Linear
+project) in the `draft` role by default or `ready` when `prd_ready=true`. **The PRD lives in the
+source — there is no loose document artifact.** Before handing the synthesized PRD to
+`lisa-prd-source-write`, record the Research run's direct usage on that artifact through
+`lisa-usage-accounting` so the PRD body carries the canonical `## Lisa Usage` ledger from creation
+time onward. If the runtime does not expose trustworthy usage, the direct entry must still be
+written with `source: unavailable` and nullable token/cost fields rather than silently omitting the
+Research row. If the call includes `ideation_ledger_payload`, pass that object through in the
+`lisa-prd-source-write` spec unchanged alongside `marker`, `dedupe_key`, and `initial_role`; this is
+the vendor-neutral handoff that lets the configured writer render an auditable run ledger without
+`research` bypassing source selection. A `source` must be configured; if it is not, stop and report
+it rather than emitting a document. The Plan flow consumes the created PRD next.

package/plugins/lisa-devin/skills/lisa-review-implementation/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: lisa-review-implementation
+description: This skill should be used when comparing a project's Lisa-managed files against Lisa's source templates to identify drift. It reads the project manifest, locates source templates, generates diffs for drifted files, and offers to upstream improvements back to Lisa.
+---
+
+# Lisa Implementation Review
+
+This skill compares the current project's Lisa-managed files against Lisa's source templates to identify drift and offer to upstream improvements back to Lisa.
+
+## Prerequisites
+
+This skill requires access to the Lisa installation directory. Either:
+1. Start Claude Code with `--add-dir ~/lisa` (or your Lisa path)
+2. Pass the Lisa directory as an argument: `/lisa-review-implementation ~/lisa`
+
+## Instructions
+
+### Step 1: Locate Lisa Directory
+
+First, determine the Lisa installation directory:
+
+1. If an argument was provided, use that path
+2. Otherwise, check if any `--add-dir` paths contain a `src/core/lisa.ts` file (Lisa's signature file)
+3. Common locations to check: `~/lisa`, `~/workspace/lisa`, `../lisa`
+
+If Lisa directory cannot be found, inform the user:
+```
+Unable to locate Lisa installation directory.
+
+Please either:
+1. Start Claude Code with: claude --add-dir /path/to/lisa
+2. Run this command with the path: /lisa-review-implementation /path/to/lisa
+```
+
+### Step 2: Read the Manifest
+
+Read the project's `.lisa-manifest` file to get the list of managed files.
+
+Parse each line to extract:
+- `strategy`: The copy strategy used (copy-overwrite, copy-contents, merge, create-only)
+- `relativePath`: The file path relative to project root
+
+Skip:
+- Lines starting with `#` (comments)
+- Empty lines
+- Files with `create-only` strategy (these are meant to be customized)
+- Files with `merge` strategy (these are intentionally combined)
+
+### Step 3: Find Source Templates
+
+For each managed file, locate its source in Lisa by checking these directories in order:
+1. `npm-package/copy-overwrite/` and `npm-package/copy-contents/`
+2. `cdk/copy-overwrite/` and `cdk/copy-contents/`
+3. `nestjs/copy-overwrite/` and `nestjs/copy-contents/`
+4. `expo/copy-overwrite/` and `expo/copy-contents/`
+5. `typescript/copy-overwrite/` and `typescript/copy-contents/`
+6. `all/copy-overwrite/` and `all/copy-contents/`
+
+The FIRST match wins (most specific type takes precedence).
+
+Detect which project types apply by checking the project for:
+- `npm-package`: package.json without `"private": true` AND has `main`, `bin`, `exports`, or `files`
+- `cdk`: presence of `cdk.json` or `aws-cdk` in dependencies
+- `nestjs`: presence of `nest-cli.json` or `@nestjs` in dependencies
+- `expo`: presence of `app.json`, `eas.json`, or `expo` in dependencies
+- `typescript`: presence of `tsconfig.json` or `typescript` in dependencies
+
+Only check type directories that match the project.
+
+### Step 4: Compare Files
+
+For each file, compare the project version against the Lisa source:
+
+1. Read both files
+2. If identical, mark as "in sync"
+3. If different, generate a diff summary
+
+Use the Bash tool with `diff` to generate readable diffs:
+```bash
+diff -u "/path/to/lisa/source" "/path/to/project/file" || true
+```
+
+### Step 5: Generate Report
+
+Create a markdown report with these sections:
+
+```markdown
+# Lisa Implementation Review
+
+**Project:** [project name from package.json]
+**Lisa Source:** [lisa directory path]
+**Generated:** [current date/time]
+
+## Summary
+
+- **Total managed files:** X
+- **In sync:** X
+- **Drifted:** X
+- **Source not found:** X
+
+## Drifted Files
+
+### [relative/path/to/file]
+
+**Source:** [lisa-type]/copy-overwrite/[path]
+**Strategy:** copy-overwrite
+
+<details>
+<summary>View diff</summary>
+
+```diff
+[diff output]
+```
+
+</details>
+
+**Recommendation:** [Brief analysis of whether this change should be upstreamed]
+
+---
+
+[Repeat for each drifted file]
+
+## Files Not Found in Lisa
+
+These files are in the manifest but their source templates couldn't be located:
+
+- [list of files]
+
+## In Sync Files
+
+<details>
+<summary>X files are in sync with Lisa</summary>
+
+- [list of files]
+
+</details>
+```
+
+### Step 6: Offer to Upstream Changes
+
+After presenting the report, ask the user which drifted files they want to copy back to Lisa.
+
+For each file the user wants to upstream:
+
+1. Confirm the target path in Lisa (e.g., `typescript/copy-overwrite/.github/workflows/ci.yml`)
+2. Use the Write tool to copy the project's version to Lisa
+3. Report success
+
+Example prompt:
+```
+I found X files that have drifted from Lisa's templates.
+
+Which files would you like to copy back to Lisa?
+1. .github/workflows/ci.yml - [brief description of changes]
+2. .claude/settings.json - [brief description of changes]
+3. All of the above
+4. None - just show me the report
+
+Select an option (or list specific numbers):
+```
+
+### Important Notes
+
+- **Never auto-upstream without confirmation** - always ask the user first
+- **Preserve the most specific type directory** - if a file exists in both `typescript/` and `all/`, upstream to where it currently exists
+- **Handle binary files gracefully** - skip comparison for non-text files
+- **Respect .gitignore patterns** - some generated files shouldn't be compared
+- For `copy-contents` files like `.gitignore`, the comparison is trickier since the project may have additional lines - highlight only if Lisa's required lines are missing
+
+## Example Usage
+
+```
+User: /lisa-review-implementation
+
+Claude: I'll review your project's Lisa-managed files against the Lisa source templates.
+
+[Locates Lisa directory]
+[Reads manifest]
+[Compares files]
+[Generates report]
+
+# Lisa Implementation Review
+
+**Project:** my-awesome-app
+**Lisa Source:** /Users/dev/lisa
+**Generated:** 2026-01-18 10:30:00
+
+## Summary
+
+- **Total managed files:** 45
+- **In sync:** 42
+- **Drifted:** 3
+- **Source not found:** 0
+
+## Drifted Files
+
+### .github/workflows/ci.yml
+
+**Source:** typescript/copy-overwrite/.github/workflows/ci.yml
+**Strategy:** copy-overwrite
+
+[diff details]
+
+**Recommendation:** This adds a new caching step that improves CI performance. Good candidate for upstreaming.
+
+---
+
+I found 3 files that have drifted. Would you like to upstream any of these changes back to Lisa?
+```

package/plugins/lisa-devin/skills/lisa-review-local/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: lisa-review-local
+description: This skill should be used when performing a code review on local changes on the current branch compared to the main branch. It uses multiple parallel agents to check for bugs, CLAUDE.md compliance, git history context, previous PR comments, and code comment adherence, then scores and filters findings by confidence level.
+disable-model-invocation: false
+---
+
+Provide a code review for the local changes on the current branch compared to the main branch.
+
+Apply the `convergent-review` rule throughout this skill: reviewers bias toward
+merge, block only concrete correctness/security/data-loss/contract failures, and
+must label every finding with severity, blocking status, failure scenario,
+evidence, and fix. Lint-owned style, formatting, taste, and speculative
+maintainability feedback are non-blocking unless a repository rule or work item
+explicitly makes them release criteria. A blocking finding without a concrete
+failure scenario is malformed and must be filtered out.
+
+One deterministic gate runs ahead of the judgement-based review and is exempt
+from the confidence filtering below, because it is decided by a script rather
+than by an agent's opinion.
+
+**Design-source gate (`design-source-of-truth` rule).** First read
+`designSource.enabled` in `.lisa.config.json`. Only boolean `false` opts out:
+omit the design-source review step; do not request DESIGN-SOURCE markers, Figma
+nodes, or Figma access for this obligation. Record `SKIPPED: designSource.enabled=false`
+in the review. Absent, true, or invalid values keep enforcement enabled.
+The separate design-value binding review below still applies.
+
+When enabled, run the gate against the branch diff before step 1:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/design-source-gate.mjs" --base=main --head=HEAD
+```
+
+Exit 0 = PASS or explicit SKIPPED, exit 1 = FAIL. A FAIL is a **blocking** review finding and is
+reported verbatim at the top of the review — it is never scored, never filtered
+by confidence, and never demoted to a nitpick. It qualifies under
+`convergent-review` because it names a concrete failure scenario: the design
+source silently diverges from the shipped product and nobody can tell which one
+is authoritative. The gate fails closed, so an unresolvable diff or an unreadable
+file is a FAIL too. Each violation is fixed one of two ways, sync-back first:
+reflect the surface in Figma and cite the node with `DESIGN-SOURCE: <figma-url>`,
+or — only when the surface genuinely does not belong in the design source — mark
+it `DESIGN-SOURCE: none — not in Figma`. Host design-system rules
+(`figma-design-system`, `design-system`, `use-the-design-library`, or the
+project's equivalent) remain authoritative about what to build; this gate only
+asks whether the source is declared. If the gate script is not present (the
+project predates the plugin version that ships it), say so explicitly in the
+review — a silent skip is not one of the exits.
+
+**Design-value binding (`design-value-binding` rule).** A separate, orthogonal
+question about the same surfaces: not *is the source declared* but *are the
+values bound*. In an axis the project publishes design variables for, a literal
+is a **blocking** finding — it is a copied number that will drift when the
+system moves. In an axis with no variable collection, the identical literal is
+correct and must not be flagged; measuring is the legitimate source there, and
+the derived values belong on the work item. Aesthetic disagreement is never a
+finding under this rule. Cite the rule; do not restate its conditions here.
+
+To do this, follow these steps precisely:
+
+1. Use a Haiku agent to check the current git state:
+   - Run `git branch --show-current` to get the current branch name
+   - Run `git log main..HEAD --oneline` to see commits on this branch
+   - Run `git diff main...HEAD --stat` to see changed files
+   - If the current branch IS main, or there are no commits/changes compared to main, do not proceed.
+2. Use another Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root CLAUDE.md file (if one exists), as well as any CLAUDE.md files in the directories whose files were modified on this branch
+3. Use a Haiku agent to analyze the branch changes:
+   - Run `git log main..HEAD --format="%s%n%b"` to get commit messages
+   - Run `git diff main...HEAD` to get the full diff
+   - Return a summary of the changes
+4. Then, launch 5 parallel Sonnet agents to independently code review the change. The agents should do the following, then return a list of issues and the reason each issue was flagged (eg. CLAUDE.md adherence, bug, historical git context, etc.):
+   a. Agent #1: Audit the changes to make sure they comply with the CLAUDE.md. Note that CLAUDE.md is guidance for Claude as it writes code, so not all instructions will be applicable during code review.
+   b. Agent #2: Read the file changes (via `git diff main...HEAD`), then do a shallow scan for obvious bugs. Avoid reading extra context beyond the changes, focusing just on the changes themselves. Focus on large bugs, and avoid small issues and nitpicks. Ignore likely false positives.
+   c. Agent #3: Read the git blame and history of the code modified, to identify any bugs in light of that historical context
+   d. Agent #4: Read previous pull requests that touched these files, and check for any comments on those pull requests that may also apply to the current changes.
+   e. Agent #5: Read code comments in the modified files, and make sure the changes comply with any guidance in the comments.
+   Each agent must apply the severity bar from `convergent-review` and return only findings that include a concrete failure scenario and evidence. Non-blocking observations may be summarized separately, but must not be presented as required changes.
+5. For each issue found in #4, launch a parallel Haiku agent that takes the diff, issue description, and list of CLAUDE.md files (from step 2), and returns a score to indicate the agent's level of confidence for whether the issue is real or false positive. To do that, the agent should score each issue on a scale from 0-100, indicating its level of confidence. For issues that were flagged due to CLAUDE.md instructions, the agent should double check that the CLAUDE.md actually calls out that issue specifically. The scale is (give this rubric to the agent verbatim):
+   a. 0: Not confident at all. This is a false positive that doesn't stand up to light scrutiny, or is a pre-existing issue.
+   b. 25: Somewhat confident. This might be a real issue, but may also be a false positive. The agent wasn't able to verify that it's a real issue. If the issue is stylistic, it is one that was not explicitly called out in the relevant CLAUDE.md.
+   c. 50: Moderately confident. The agent was able to verify this is a real issue, but it might be a nitpick or not happen very often in practice. Relative to the rest of the changes, it's not very important.
+   d. 75: Highly confident. The agent double checked the issue, and verified that it is very likely it is a real issue that will be hit in practice. The existing approach is insufficient. The issue is very important and will directly impact the code's functionality, or it is an issue that is directly mentioned in the relevant CLAUDE.md.
+   e. 100: Absolutely certain. The agent double checked the issue, and confirmed that it is definitely a real issue, that will happen frequently in practice. The evidence directly confirms this.
+6. Filter out any issues with a score less than 80.
+6a. Filter out any blocking issue that does not name a concrete failure scenario in one of the `convergent-review` blocker classes. Keep it only as non-blocking context if it is useful.
+7. Write the review to claude-review.md. When writing your review, keep in mind to:
+   a. Keep your output brief
+   b. Avoid emojis
+   c. Reference relevant files and line numbers
+8. Briefly summarize claude-review.md as direct output to the user
+
+Examples of false positives, for steps 4 and 5:
+
+- Pre-existing issues
+- Something that looks like a bug but is not actually a bug
+- Pedantic nitpicks that a senior engineer wouldn't call out
+- Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
+- General code quality issues (eg. lack of test coverage, general security issues, poor documentation), unless explicitly required in CLAUDE.md
+- Findings that restate lint-owned style, formatting, taste, or speculative cleanup as blockers without a concrete failure scenario
+- Issues that are called out in CLAUDE.md, but explicitly silenced in the code (eg. due to a lint ignore comment)
+- Changes in functionality that are likely intentional or are directly related to the broader change
+- Real issues, but on lines that were not modified in the current branch
+
+Notes:
+
+- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
+- Use git commands to analyze local changes (not `gh` commands for remote PRs)
+- Make a todo list first
+- You must cite each bug with file path and line number (eg. if referring to a CLAUDE.md, you must reference it)
+- For your final output, follow the following format precisely (assuming for this example that you found 3 issues):
+
+---
+
+### Code review for branch `<branch-name>`
+
+Reviewed X commits with changes to Y files.
+
+Found 3 issues:
+
+1. **<brief description of bug>** (CLAUDE.md says "<...>")
+   - File: `path/to/file.ts:L10-L15`
+
+2. **<brief description of bug>** (some/other/CLAUDE.md says "<...>")
+   - File: `path/to/other-file.ts:L25-L30`
+
+3. **<brief description of bug>** (bug due to <reasoning>)
+   - File: `path/to/another-file.ts:L5-L8`
+
+---
+
+- Or, if you found no issues:
+
+---
+
+### Code review for branch `<branch-name>`
+
+Reviewed X commits with changes to Y files.
+
+No issues found. Checked for bugs and CLAUDE.md compliance.
+
+---