Receiving Change Review

---
name: receiving-change-review
description: |
  Phase 2 of /peer-review. Use after generalist dispatch completes to aggregate findings,
  present results, and manage specialist lifecycle.
---

# Receiving Change Review

Phase 2 of `/peer-review`: aggregate findings, present results, manage specialist lifecycle.

## Step 1: Verify Coverage

Union of `files_reviewed` across all generalist responses should equal the full file set from the change.

If gaps exist: report which files were missed. Consider re-dispatching for missed files.

## Step 2: Deduplicate Findings

- Same file + overlapping line range = candidate duplicate
- Make a semantic judgment on whether descriptions refer to the same issue
- Keep the higher-confidence finding when deduplicating
- Preserve both if they describe genuinely different issues at overlapping locations

## Step 3: Reconcile Verdicts

| Condition | Overall Verdict |
|---|---|
| Any `no` | `no` |
| Any `with_fixes` (no `no`) | `with_fixes` |
| All `yes` | `yes` |

Preserve per-partition verdicts in the output so users can see which areas are clean vs. need fixes.

## Step 4: Aggregate Specialist Recommendations

- Group by concern type (enum-normalized)
- Merge file lists for the same concern type across generalists
- Deduplicate line ranges

## Step 5: Check History for Specialist Emergence

**This step runs BEFORE appending the current review to history** (so the current review's patterns don't count toward their own emergence threshold).

1. Read `.claude/peer-review/history.jsonl` if it exists
2. Count distinct `pattern` values per concern `type` across entries
3. If any concern type has 3+ distinct patterns: prepare emergence prompt

Present prompt to user:

```
[peer-review] "<type>" flagged in N reviews for this project.
  Distinct patterns: <pattern1>, <pattern2>, <pattern3>.
Create a project specialist? (y/n)
```

Three occurrences of the same pattern is repetition, not emergence. Three *different* manifestations of a concern type across reviews — that's emergence.

## Step 6: Append to History

Do NOT hand-write the JSONL line. Pipe the aggregated review to the script:

```bash
printf '%s' "$AGGREGATED_JSON" \
  | bash "${CLAUDE_PLUGIN_ROOT}/scripts/append-review-history.sh" --revision <short-id>
```

`$AGGREGATED_JSON` is the merged result of Steps 2–4: `files_reviewed`,
`findings`, `specialist_recommendations`, `verdict`. The script derives
`timestamp`, `findings_count` (tallied by severity) and — critically —
`concerns`, mapping each specialist recommendation's `concern` → `type` and
`rationale` → `pattern`. It creates the directory, appends with `tee -a`, and
refuses to touch the file if the input is not valid JSON.

**Why a script and not a template.** This step used to show the JSONL shape with
`"concerns":[{"type":"<enum>","pattern":"<description>",…}]` and never said where
those values came from — and the generalist schema does not use those names, it
returns `specialist_recommendations[]` with `concern` and `rationale`. So the
producer had no instruction while Step 5's emergence check depended on the field.
Measured on this repo: **3 of 3 history entries had `concerns: []`**, one of them
recording 7 findings. Emergence had been inert since the plugin shipped.

Re-stating the mapping in prose would repeat the bet that already failed — it was
implicitly required and skipped every time. `tests/test-review-history.sh` pins
the derivation, including the specific regression: a review with findings must
never record `concerns: []`.

## Step 7: Present Results

### Default (local) format:

```
## Peer Review: <change-id short>

### Findings
#### Critical (N)
- [change-reviewer] description — file:line

#### Important (N)
- [change-reviewer] description — file:line

#### Minor (N)
- [change-reviewer] description — file:line

### Verdict
Ready to merge: Yes / No / With fixes
Reasoning: <one sentence>

### Specialist Recommendations
- **error-handling**: 3 catch blocks in src/api/client.rs (lines 45-90, 120-135)
- **type-design**: New SessionState enum in src/types.rs

### Actions
- /peer-review --deep errors    # dispatch recommended specialist
- /peer-review --post           # post findings to GitHub PR
```

### GitHub (`--post`) format:

Format as a PR comment via `gh pr comment`. If no open PR found:

```
Error: No open PR found for bookmark '<name>'. Create one first or omit --post.
```

### JSON (`--json`) format:

Output raw JSON — the aggregated response with all findings, verdicts, and recommendations.

## Step 8: If Specialist Emergence Approved

Create `.claude/peer-review/specialists/<concern-type>.md` seeded with:

```markdown
---
name: <concern-type>
description: Project specialist for <concern-type> patterns
model: sonnet
---

## Role

You are a specialist reviewer for <concern-type> issues. You review specific files and line ranges flagged by the generalist reviewer.

## Patterns Observed in This Project

<list of accumulated distinct patterns from history with file references>

## Relevant Guidelines

<applicable CLAUDE.md rules>

## Review Focus

Analyze the flagged locations for <concern-type> issues. Return structured JSON findings using the same schema as the generalist, but with deeper analysis for your specialty.

## Proposed Refinements

(Generalist proposals appear here. Only humans promote them into the active prompt.)
```

## Step 9: If --deep Specified

Dispatch specialists for flagged concerns:

1. **Discovery order**: project (`.claude/peer-review/specialists/`) → user-global (`~/.claude/peer-review/specialists/`) → plugin built-in (`peer-review-jj/agents/`)
2. First match for a concern type wins — no merge, no inheritance
3. Scope each specialist to flagged locations only (specific files and line ranges)
4. Include specialist memory summary — prior patterns with recency, framed as context not checklist:

> "Patterns previously observed in this project (for context, not as a checklist): broad exception types (3x, last seen 2026-02-10), missing error context in retry paths (2x, last seen 2026-03-01)."

5. Aggregate specialist findings into final output

## Specialist Refinement Proposals

If a generalist proposes a refinement to an existing specialist, append it to the specialist's `## Proposed Refinements` section:

```markdown
- [YYYY-MM-DD] change-reviewer flagged: "<proposal>" (seen in <file>:<lines>)
```

Use `tee -a` or similar append operation. Only humans promote proposals into the active prompt.

## Verification Protocol

- Do NOT blindly implement findings
- Push back on false positives with technical reasoning
- Flag findings that contradict project decisions (CLAUDE.md, architectural choices)
- This applies whether a human or an orchestrating agent is acting on findings