--- name: review-jev-scenarios model_tier: light description: | Use when: an ADDITIONAL, machine-scored FUNCTIONAL review is wanted — which user scenarios a PR likely changes — never replacing any other reviewer. Dispatched by review-orchestrator in Wave B, via the CLI (`keryx review jev-scenarios`), when `review.jev.scenarios: true` in .metaproject/tasks.config.json and a Jev/OpenRouter credential is resolvable. It is not an LLM sub-agent: there is nothing to dispatch through a platform-native agent mechanism, and no prose is generated by a model — Jev only answers one `noul` "does this change alter this scenario's behaviour?" per scenario whose linked code the diff touches; keryx writes every word of every finding. NOT for: discovering scenarios nobody documented (it reads existing gdwiki user-scenario pages, PRD requirement/scenario sections, and README/docs "how to" sections — a scenario that exists only in someone's head is invisible to it), and not a substitute for manually walking the checklist it produces. triggers: - "jev scenarios" - "functional review" - "review --jev-scenarios" metadata: author: "MrCipherSmith" version: "1.0.0" category: "review" compatible_harnesses: "cursor,codex,zed,opencode,claude" engine: "jev" origin: "authored" license: "MIT" --- # Review — Jev Scenarios (deterministic functional review) An ADDITIONAL orchestrator reviewer, flow 332. It is a **keryx program**, not an LLM sub-agent: `review-orchestrator` never dispatches a platform-native agent for it, it runs `keryx review jev-scenarios` and reads the `--json` output. Every finding is composed by keryx; Jev ("System One" on OpenRouter) supplies only one `noul` probability per scenario — never prose. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. --- ## What it does 1. Gathers user scenarios deterministically from three sources: gdwiki pages of type `user-scenario` (`.metaproject/wiki/user-scenarios/**`), PRD requirement/scenario sections (`docs/requirements/**`, any heading matching scenario/requirement/user story/use case), and README/docs "how to" sections (`README.md`, `docs/docs/**`). 2. Extracts each scenario's own links to code — markdown links and inline code-span file references, the same convention `src/wiki/backlinks.ts` already established for the wiki's own code edges. 3. Computes, per scenario, which of its linked files the diff actually touches (a fact) and whether a test in the diff covers a touched link (a fact). 4. For every scenario with at least one touched link, asks Jev **one `noul`**: "does this change alter this scenario's behaviour?" — batched under the vendor's 64k token budget, capped at `--max-calls` (default 150), with every drop reported. 5. Emits a **manual-check list**: every scenario at/above threshold (default 0.5), ranked, each with its touched links as evidence — for a human to walk before merge. 6. Emits a `minor` finding for each likely-affected scenario with **no test in the diff covering it** (a fact) — severity fixed at `minor`: this flags attention over a functional scenario, it does not assert a defect. --- ## Input Contract Not dispatched with a prompt — invoked as a CLI command: ```text keryx review jev-scenarios (--diff | --pr | --scope ) [--max-calls ] [--threshold <0..1>] [--repo ] [--model ] [--fixtures ] [--json] ``` `review-orchestrator` passes `--scope ` — the same file every other reviewer's dispatch already reads — so this reviewer's "touched by this diff" facts agree with the round's own scope. --- ## Opt-in and privacy Refuses before any read or network call unless `.metaproject/tasks.config.json` declares: ```json { "review": { "jev": { "scenarios": true } } } ``` Every scenario's text sent to Jev is redacted first through `src/security/service.ts` — the same floor every other Jev-backed mode in this repository already applies. No cache or output file stores a credential. --- ## Output Contract Emits a `REVIEW_RESULT`-shaped object matching `.metaproject/skills/gdskills/review/review-orchestrator/reviewer-finding.schema.json` — `status`, `reviewer: "review-jev-scenarios"`, `summary`, `findings`, `stats` — under `--json`, plus one orchestrator-facing extra: `checklist` (the ranked manual-check list described above). Its findings merge into the consolidated array exactly like any other reviewer's: same Quality Gate, same dedup, same Wave C verification. --- ## Orchestrator integration - `keryx review reviewers --json` lists it under `bundled` with `"engine": "jev"`. - `review-orchestrator` dispatches it in **Wave B**, alongside the domain/ convention reviewers and flow 330's `review-jev-rules`/flow 332's `review-jev-risk`, when the opt-in is on and a Jev/OpenRouter credential resolves. When either is false it is **skipped with the stated reason**, recorded in `Skipped reviewers` — never silently absent. - It is **ADDITIONAL**: it never replaces any domain reviewer's own read of the diff. - The consolidated report's "Manual verification" section (or equivalent) should surface `checklist` verbatim alongside any findings — a scenario that scored below the finding threshold but above the checklist threshold is still worth a human glance even though it produced no finding. --- ### Shared laws (every reviewer) 1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it. 2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere. 3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems. 4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported. This reviewer satisfies all three by construction: severity is fixed at `minor` — never higher — and `evidence` always names the scenario's linked code and the exact files this diff touched (never an unreproducible claim); a scenario is only asked about when a real link of its own is in the diff, never a hypothetical connection; and each scenario is its own class with its own `dedupe_key`, so there is nothing to collapse across sites. --- ## Red Flags | Rationalization | Why it is wrong | |---|---| | "Jev said 0.9, so this scenario is definitely broken" | A `noul` score is a probability that behaviour changed, not a verdict — it only ever produces a `minor` finding, and only when paired with the separate "no covering test" fact | | "This PRD scenario links to a huge, frequently-touched file, so the match is meaningless" | Down-weighted after a live check (`SCENARIO_LINK_FANOUT_THRESHOLD`): a link to a file referenced by more scenarios than that only still counts as touched when the scenario's own text names one of the diff's touched exported symbols — read the scenario's own text before assuming a surviving entry is still spurious | | "No entries in checklist means nothing changed functionally" | Discovery only covers three sources (gdwiki `user-scenario` pages, `docs/requirements/**`, README/docs "how to" sections); a scenario that exists only in someone's head, or in a doc outside those three locations, is invisible to this reviewer | | "checklist is empty so scenarioSources must be empty too" | `scenarioSources` lists every discovered scenario; `checklist` lists only those with a touched link at/above threshold — a project can have hundreds of scenarios discovered and zero touched by a given diff | --- ## Verification Before trusting a run's findings: 1. Read `selection.notApplicable`/`selection.scenariosSkipped` in the `--json` output — a scenario with no touched link was never asked, and a capped run may have skipped some that were. 2. Spot-check a `checklist` entry against the scenario's own source (`id` names the file, and for a PRD/README section, the heading): does the touched link actually sit inside the part of the diff that matters for that scenario, or did a large, widely-linked file produce a spurious match? 3. Confirm every finding carries `reviewer: "review-jev-scenarios"` and a `dedupe_key` — both are required for the orchestrator's Quality Gate and Wave C verification to route it correctly. --- ## Scope Boundaries | Concern | This skill | Use instead | |---------|------------|-------------| | Which documented user scenarios a diff likely changes | YES | — | | Discovering an undocumented scenario | NO | a human, or write the scenario down first | | Judging whether a reported finding is real | NO | `review-verifier` | | A risk map of the diff's hunks | NO | `review-jev-risk` |