add in-repo pr-review skill and align test fast loop docs

.cursor/skills/plan-prompts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-prompts
-description: Generate per-PR Cursor execution prompts in `plans/CURSOR-PROMPTS-*.md` from an existing `plans/PLAN-*.md`. Use when the user asks to split implementation into Cursor-ready PR prompts with strict in-scope/out-of-scope guardrails.
+description: Generate per-PR Cursor execution prompts in `plans/CURSOR-PROMPTS-*.md` from an existing `plans/PLAN-*.md`. Each prompt must include `## Tests to run (iteration loop)` (pytest file subset + rationales) between Deliverables and Tests per TEST-SUITE-FAST-LOOP. Use when the user asks to split implementation into Cursor-ready PR prompts with strict in-scope/out-of-scope guardrails.
 disable-model-invocation: true
 ---
 
@@ -51,11 +51,23 @@ Each PR prompt must include all of:
 - **Scope** with concrete deliverables mapped to plan section
 - **Out of scope (do NOT touch)** list mirroring plan boundaries
 - **Deliverables** numbered and testable
-- **Tests** command and expected result format (counts only if known)
+- **`## Tests to run (iteration loop)`** — pytest **file** subset for fast local iteration (see below); must appear **after Deliverables and before the full Tests section**
+- **Tests** command and expected result format for the full or plan-required run (counts only if known)
 - **Sentinel checks** (`rg` patterns) where scope enforcement is critical
 - **Manual evidence** commands when plan requires runtime proof
 - **Definition of Done** checklist with PR title + branch convention
 
+### Tests to run (iteration loop) — required subsection
+
+Per [`propose/TEST-SUITE-FAST-LOOP-PROPOSE.md`](../../../propose/TEST-SUITE-FAST-LOOP-PROPOSE.md) and [`plans/PLAN-TEST-SUITE-FAST-LOOP.md`](../../../plans/PLAN-TEST-SUITE-FAST-LOOP.md) PR-2:
+
+- Add a markdown section with the **exact heading** `## Tests to run (iteration loop)` inside the fenced **Prompt** block, **immediately after** `## Deliverables` and **before** `## Tests`.
+- Content: bullet list of `tests/test_*.py` paths, each with a **one-line rationale** tied to the PR’s code paths.
+- **Merge gate:** state that the **full** default suite (`pytest tests`, `JAVA_CODEBASE_RAG_RUN_HEAVY` unset or `0`) is enforced at merge time by CI once the repo workflow exists; the iteration list is for speed only.
+- **Docs-only (UC15):** if the PR is documentation-only with no test signal, use an explicit empty pattern, e.g. a single bullet `*(none — docs-only change; full suite still runs in CI.)*` — do not invent a fake file list.
+
+This heading must stay verbatim so reviewers (and the repo **`pr-review`** skill in `.cursor/skills/pr-review/`) can grep for it.
+
 ## Style rules
 
 - Keep prompts self-contained; an agent should not re-derive design.
@@ -95,6 +107,15 @@ Read the PR-XX section first. The plan is the source of truth.
 1. <deliverable>
 2. <deliverable>
 
+## Tests to run (iteration loop)
+
+Run only these files during local iteration; full suite is the merge gate (CI on PR + `master`).
+
+- `tests/test_<file>.py` — <one-line rationale>
+- `tests/test_<other>.py` — <one-line rationale>
+
+Docs-only PRs (UC15): use a single bullet such as *(none — docs-only change; full suite still runs in CI.)* instead of inventing paths.
+
 ## Tests
 Run: `<command>`
 Expected: <result format / count if known>
@@ -117,6 +138,7 @@ Expected: <result format / count if known>
 - [ ] Prompt file covers every PR from the plan in order
 - [ ] Each prompt has explicit scope and out-of-scope
 - [ ] Deliverables are numbered and verifiable
+- [ ] Each generated prompt includes **`## Tests to run (iteration loop)`** between Deliverables and Tests (or the UC15 docs-only line)
 - [ ] Tests and sentinel checks are present where needed
 - [ ] No scope drift from plan decisions
 

.cursor/skills/plan-prompts/examples.md

@@ -35,16 +35,23 @@ Status: **active**. One prompt per PR; each prompt is self-contained.
 If you need to touch these areas, stop and ask.
 ```
 
-## Example deliverables + tests
+## Example deliverables + iteration subset + tests
 
 ```markdown
 ## Deliverables
 1. Add schema DDL for `Client` + relation table.
 2. Wire create/drop lifecycle.
 3. Add extraction tests for declared client rows.
 
+## Tests to run (iteration loop)
+
+Run only these files during local iteration; full suite is the merge gate (CI on PR + `master`).
+
+- `tests/test_client_node_extraction.py` — exercises new `Client` rows and extraction.
+- `tests/test_ast_graph_build.py` — schema and graph build paths touched by DDL wiring.
+
 ## Tests
-Run: `python -m pytest tests/test_client_node_extraction.py -q`
+Run: `.venv/bin/python -m pytest tests/test_client_node_extraction.py tests/test_ast_graph_build.py -v`
 Expected: all tests pass.
 
 ## Sentinel checks

.cursor/skills/plan-prompts/reference.md

@@ -8,13 +8,15 @@ Use this when converting `PLAN-*` into `CURSOR-PROMPTS-*`.
 2. Scope is locked to one PR section only.
 3. Out-of-scope is explicit and enforceable.
 4. Deliverables are concrete and numbered.
-5. Tests + evidence are specific, not generic.
+5. **Iteration subset** (`## Tests to run (iteration loop)`) lists `tests/test_*.py` bullets with one-line rationales (or UC15 docs-only line) between Deliverables and Tests.
+6. Tests + evidence are specific, not generic.
 
 ## Mapping rule (plan -> prompt)
 
 - Plan PR section title -> Prompt PR section title
 - Plan file-by-file changes -> Prompt "Scope" + "Deliverables"
-- Plan tests list -> Prompt "Tests"
+- Plan tests list -> Prompt "Tests" (full / plan-required command)
+- Fast iteration subset -> Prompt **`## Tests to run (iteration loop)`** (between Deliverables and Tests; see `plan-prompts` skill)
 - Plan done definition -> Prompt "Definition of Done"
 - Plan risks/out-of-scope -> Prompt "Out of scope" + sentinel checks
 
@@ -23,5 +25,6 @@ Use this when converting `PLAN-*` into `CURSOR-PROMPTS-*`.
 - Mixing two PR scopes into one prompt
 - Dropping out-of-scope items from the plan
 - Vague tests ("run tests") without commands
+- Missing **`## Tests to run (iteration loop)`** between Deliverables and Tests (unless the PR is docs-only per UC15)
 - Missing branch/base/title conventions
 - Adding new architecture decisions not present in the plan

.cursor/skills/pr-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pr-review
+description: >-
+  Reviews pull requests against plan scope, requires pasted pytest subset
+  evidence plus green full-suite CI, and rejects checkbox-only test claims.
+  Use when reviewing a PR, approving a merge, or checking an agent handoff.
+disable-model-invocation: true
+---
+
+# PR review
+
+Use this checklist when reviewing a PR that was driven by a written plan or a **`plan-prompts`** / `CURSOR-PROMPTS-*` task handoff.
+
+## 1. Scope and diff hygiene
+
+- [ ] Diff matches stated scope; no drive-by refactors or scope leaks from the plan’s **Out of scope** list.
+- [ ] If the task prompt listed sentinel `git grep` patterns, they are **absent** from `git diff master..HEAD` (when that contract applies).
+
+## 2. Test evidence — iteration subset (mandatory)
+
+The PR body or thread must include **pasteable proof** that the author ran the files declared under **`## Tests to run (iteration loop)`** in the task prompt.
+
+**Acceptable**
+
+- The **exact** command line (e.g. `.venv/bin/python -m pytest tests/test_foo.py tests/test_bar.py -v` or equivalent).
+- The **exit code** or explicit pass summary tied to that command (e.g. `exit 0`, or pytest’s final `N passed` line immediately after the command).
+
+**Not acceptable (reject the review)**
+
+- Only a checkbox such as `- [x] subset ran` or “tests passed” **without** the command and outcome above.
+- A vague “ran pytest” with no file list and no exit code.
+- Substituting a different file list than the prompt declared, without explanation.
+
+If the task prompt declared **docs-only** (empty iteration list per UC15), subset evidence is: state that no test files were required for iteration, and still require **full-suite CI green** below.
+
+**Subset green does not replace the merge gate:** If full-suite CI is red, the PR is not merge-ready even when the declared subset passed locally.
+
+## 3. Test evidence — full suite / CI (mandatory when repo CI exists)
+
+When this repository has a required GitHub Actions workflow that runs the **full** default suite (e.g. `pytest tests` with `JAVA_CODEBASE_RAG_RUN_HEAVY` unset or `0`):
+
+- [ ] The PR description or review comment includes a **link** to a **green** Actions run for the **full** suite on **this PR** at the **same commit** being reviewed (or the tip the reviewer approves).
+
+If CI is not yet enabled for the repo, note that in the review; once the workflow exists, **withhold approval** until both §2 and §3 are satisfied.
+
+## 4. Plan and docs
+
+- [ ] PR body references the plan/propose when the work was plan-driven.
+- [ ] `tests/README.md` or other operator docs changes remain consistent with repo conventions.
+
+## 5. Manual / product evidence
+
+Reproduce or spot-check any plan-required manual command **after** §2–§3 are satisfied (or in parallel if independent).
+
+---
+
+## Self-check (dry-run)
+
+- **Fail:** Review comment says “subset verified [x]” with no pytest command → **does not meet §2**.
+- **Pass:** Pasted command, pytest summary / `exit 0`, and link to green full-suite run on the PR commit.

docs/skills/java-codebase-explore.md

@@ -18,7 +18,7 @@ when_to_load:
   - "onboard onto this code"
   - "write a propose doc for redesign of <component>"
 when_not_to_load:
-  - routine PR review (use a review skill such as `cursor-pr-review` if you have it; example external skill, not shipped from this repo)
+  - routine PR review (use the **`pr-review`** project skill at `.cursor/skills/pr-review/` in this repo, or your own review checklist)
   - single-question lookups answerable by one MCP call
   - editing existing code where the agent is already oriented
 ---