review-resolve

name	review-resolve
description	Verify review finding resolutions against actual source code and write back verification metadata
allowed-tools	Agent, Read, Write, Edit, Glob, Grep, Bash(grep:*), Bash(ls:*), Bash(find:*), Bash(mkdir:*), Bash(git log:*), Bash(git diff:*), Bash(git show:*), Bash(.claude/scripts/rm-tmp.sh:*), Bash(python .claude/scripts/render-review.py:*)

Review Verification

You are the review verifier: re-read the updated review document, verify each finding's resolution status against the actual source code, and write the verification result back as verification metadata.

Input

The user specifies a path to the review document (markdown). When the argument is $ARGUMENTS, interpret it as the path to the review document.

Review Document Format

The review document is generated by parallel-review and contains a metadata marker for each finding. It is assumed that review-respond has already appended the triage / estimate / status fields:

### {finding-id} — `{location}`

- **Reviewer:** {reviewer-name}

**Finding:**

{description}

<!-- METADATA({finding-id}) -->
- **Triage:** 🔧 Will Fix (assignee: cpp-sensei) — Valid finding
- **Estimate:** ▶️ Maintain — Cost: M, Future: S, Signals: b,d
- **Status:** 🟢 Fixed — Added null check
<!-- /METADATA({finding-id}) -->

---

Determine each finding's current state from the fields present between the markers:

• Empty between markers → not yet triaged.
• Only Triage: 🔧 Will Fix → triaged, estimate not yet completed.
• Triage: 🚫 Won't Fix → confirmed as no action needed.
• Estimate: ▶️ Maintain with no Status: → estimated, fix not yet completed.
• Estimate: 🔻 Downgrade → resolved as no action needed at the estimate stage.
• Estimate: 🚧 Alternative with no Status: → resolved as alternative handling at the estimate stage, FIXME not yet added.
• Status: 🟢 Fixed → fix completed (Maintain fix, or FIXME added for Alternative).

review-resolve appends a verification field in one of the following forms:

• ✅ Verified — {brief description of the verification result} — Resolved.
• 💬 Feedback — {what is missing and what is required for full resolution} — Feedback required.

For Unresolved findings, do not write a verification value.

Value constraints

• Single line only (no newlines). Write long descriptions in other sections of the document (e.g., feedback details), and keep the metadata value as a summary.
• No deletion (append only).

Common Sub-Agent Instructions

For common prohibitions, see .claude/rules/sub-agent.md. The body of each sub-agent prompt is stored in external templates under templates/*.md (each has a template_id in its frontmatter). When invoking a sub-agent via the Agent tool, the leader passes a launch prompt that instructs the sub-agent to "Read the template and follow its instructions" with variable values substituted in. Sub-agents include template_id in their return value. The leader checks that the returned template_id matches the UUID specified for each step (hard-coded per step below); if it does not match, the leader relaunches that sub-agent.

For launch-prompt-completeness rules, see .claude/rules/sub-agent.md § Launch Prompt Completeness.

Internal Processing (Intermediate Files)

The leader (you) does not place the verification body in context.

Working directory

{tmp_dir} = .claude/tmp/review-resolve-{timestamp}/
{tmp_dir}/verifications/{id}.json  ← Output from the verification sub-agent (one file per finding)

At the start of Step 1, the leader creates {tmp_dir} with mkdir -p {tmp_dir}/verifications. After Step 4 completes, the leader removes it with .claude/scripts/rm-tmp.sh {tmp_dir}.

events.jsonl

events.jsonl lives in the same directory as the markdown, named {basename}.events.jsonl (e.g., review-round1.md → review-round1.events.jsonl; hereafter {events_path}). Format:

{"id":"C-1","field":"verification","value":"✅ Verified — Null check fix is accurate"}
{"id":"M-1","field":"verification","value":"💬 Feedback — LOG_ERROR is missing in the else branch at line 85"}

Use the Write tool for output. Bash cat heredoc is unusable because apostrophes inside values (e.g., Won't) break the outer quoting.

Unresolved findings (not yet triaged / estimate not yet completed / fix not yet completed) are not written to events.jsonl (they are not at the stage of receiving a verification).

Step 1 — Analysis (delegate to the analysis sub-agent)

Launch via Agent(subagent_type="review-helper", prompt=...). Task-specific instructions are stored in the templates/analyze.md external template. Example launch prompt:

As your first action, you MUST Read `.claude/skills/review-resolve/templates/analyze.md`. Do not perform any other judgment, action, or tool call before the Read completes. After reading, follow its instructions.

Variables (substitute into the template's {{...}} placeholders):
- document_path: {document_path}

Round-specific overrides (apply after following the template's instructions):
- (none)

Include `template_id` (Read from the template's frontmatter) in the return value.

Receive the return value from the sub-agent ({total, by_assignee, template_id}). Verify that template_id matches 5d9e2c8a-1f74-4b63-a9d8-3c5f7e1b9a42. If it does not match, relaunch the sub-agent.

Step 2 — Verify each finding (delegate in parallel per specialist)

Loop over by_assignee from Step 1, and for each {assignee, ids} launch a verification sub-agent in parallel via Agent(subagent_type=assignee, prompt=...) (the agent definition's persona and specialist perspective are auto-loaded).

Example launch prompt (do not include the persona). Task-specific instructions are stored in the templates/verify.md external template:

As your first action, you MUST Read `.claude/skills/review-resolve/templates/verify.md`. Do not perform any other judgment, action, or tool call before the Read completes. After reading, follow its instructions.

Variables (substitute into the template's {{...}} placeholders):
- ids: {ids}
- document_path: {document_path}
- tmp_dir: {tmp_dir}

Round-specific overrides (apply after following the template's instructions):
- (none)

Include `template_id` (Read from the template's frontmatter) in the return value.

Receive the return value from each verification agent ({items: [{id, outcome}, ...], template_id}). Verify that template_id matches 8a1f5c9b-2e73-4d64-9c1e-8b3d7f2a5e94. If it does not match, relaunch that agent. Do not place the verification body in context (the return value contains only items).

Step 3 — Verification report and reflection (delegate to the aggregator sub-agent)

The leader (you) does not place the verification body in context.

Launch procedure:

1. Launch a new sub-agent via Agent(subagent_type="review-helper", prompt=...). Task-specific instructions are stored in the templates/compile.md external template. Example launch prompt:

As your first action, you MUST Read `.claude/skills/review-resolve/templates/compile.md`. Do not perform any other judgment, action, or tool call before the Read completes. After reading, follow its instructions.

Variables (substitute into the template's {{...}} placeholders):
- tmp_dir: {tmp_dir}
- document_path: {document_path}
- events_path: {events_path}

Round-specific overrides (apply after following the template's instructions):
- (none)

Include `template_id` (Read from the template's frontmatter) in the return value.

2. Receive the return value from the aggregator sub-agent ({events_path, summary_path, summary_line, resolved_count, feedback_count, unresolved_count, template_id}). Verify that template_id matches 1c5e8b2f-7d34-4a96-b8c1-5e9a3f7d2c84. If it does not match, relaunch the sub-agent.

3. The leader removes {tmp_dir} in one shot:

   .claude/scripts/rm-tmp.sh {tmp_dir}
   

Step 4 — Completion report

The leader displays the summary_line received from the aggregator sub-agent on the console. Read summary_path (resolve-summary.md, available before {tmp_dir} is removed) only if a detailed report is needed.