review-respond

name	review-respond
description	Triage, estimate, fix, self-review, and update the review document for review findings
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(git add:*), Bash(git commit:*), Bash(git status:*), Bash(cmake:*), Bash(make:*), Bash(clang-format:*), Bash(cmake-format:*), Bash(.claude/scripts/rm-tmp.sh:*), Bash(python .claude/scripts/render-review.py:*)

Review Respond

You act as the review-respond leader: process the review document, delegate the initial triage to a separate sub-agent, have specialist sub-agents estimate the Will Fix findings, delegate fixes to the appropriate specialist agents, ensure quality through self-review, and finally reflect the accumulated metadata into the review document via render-review.py.

The review-respond leader does not take on the role of triage, estimate, or fix worker themselves; the leader orchestrates the entire review-respond process and aggregates / decides on its outcomes. Triage, estimate, and fix work is delegated entirely to sub-agents.

Input

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

Options

• --commit (default OFF) — Create a commit for each finding's fix.
• --no-confirm (default OFF) — Skip the user confirmation immediately after the estimate. Default (when not specified) is confirm-on.

--commit option

When enabled, in Step 3 each completed fix per finding is committed to git.

Commit rules

• Granularity: Commit per finding whenever possible. The ideal is one commit per finding fix.
• Multiple findings on the same file: Even when fixing several findings on the same file in sequence, commit each finding's fix individually.
• Commit message: Describe the fix concisely in 1–3 lines. Do not include the finding ID (C-1, M-1, etc.) in the commit message.
• Staging: Stage only the source-code files related to the fix (do not use git add -A). Do not commit the review document.
• Relation to build verification: Commit after Step 4 (build verification). If a build error occurs, include the build fix in the commit as well.

Commit message example

fix: Add null check before accessing output pointer

--no-confirm option

When not specified (default), the integrated summary (a single table merging review + triage + estimate) is displayed on the console immediately after Step 2's estimate completes, and the leader waits for user confirmation before proceeding to the fix step. Confirmation is not performed right after triage.

When --no-confirm is specified, confirmation is skipped and the flow proceeds to the fix step after the estimate completes. The leader does not Read summary_path written by the aggregator sub-agent (to avoid bloating the leader's context).

When an upper orchestrator such as review-rounds takes on the review-respond leader role, that orchestrator's confirmation flag overrides this default (confirm OFF if review-rounds' --confirm is OFF, confirm ON if ON).

Review document format

The review document is generated by parallel-review and contains a metadata marker (<!-- METADATA({finding-id}) --> … <!-- /METADATA({finding-id}) -->) for each finding:

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

- **Reviewer:** {reviewer name}

**Finding:**

{description of the issue}

<!-- METADATA({finding-id}) -->
<!-- /METADATA({finding-id}) -->

---

review-respond and review-resolve append the following fields between the markers:

• triage (set by review-respond Step 1) — Value format: 🔧 Will Fix (assignee: {specialist}) — {reason} / 🚫 Won't Fix — {reason no action is needed}.
• estimate (set by review-respond Step 2) — Value format: ▶️ Maintain — Cost: {S/M/L}, Future: {S/M/L}, Signals: {none\|a,b,c,d,e,f} / 🔻 Downgrade — Cost: ..., Future: ..., Signals: ... — {downgrade reason} / 🚧 Alternative — Cost: ..., Future: ..., Signals: ... — FIXME insertion: {direction}.
• status (set by review-respond Step 3) — Value format: 🟢 Fixed — {concise description of the fix}.
• verification (set by review-resolve) — Value format: ✅ Verified — {concise description of the verification result}.

Value constraints

• Single line only (no newlines). Long rationale belongs in the finding body; metadata values stay summary-level.
• Append-only (no deletion).
• For the same (id, field), last write wins.

Emoji mapping table

• triage / Step 1 / Will Fix → 🔧 (confirmed as a target for fixing)
• triage / Step 1 / Won't Fix → 🚫 (confirmed as not requiring action)
• estimate / Step 2 / Maintain → ▶️ (uphold the triage decision and proceed with the fix)
• estimate / Step 2 / Downgrade → 🔻 (overturn the triage decision and do not fix; no alternative)
• estimate / Step 2 / Alternative → 🚧 (overturn the triage decision but substitute with a lighter measure such as adding a FIXME comment)
• status / Step 3 / Fixed → 🟢 (fix complete)
• verification / review-resolve / Verified → ✅ (verification complete)

Common sub-agent instructions

For the common prohibitions, see .claude/rules/sub-agent.md. The body of the prompt for each sub-agent is stored in external templates under templates/*.md (each carries a template_id in its frontmatter). When launching via the Agent tool, the leader sends a launch prompt that tells the sub-agent to "Read the template and follow its instructions" with the variable values filled in. The sub-agent includes template_id in its return value. The leader checks that the returned template_id matches the UUID specified for that step (hardcoded per step, see below); on mismatch, relaunch that sub-agent.

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

Internal processing (intermediate files)

Each decision is written to an intermediate file, and the aggregator sub-agent compiles them. The leader (you) does not load the body of any decision into context.

Working directory

{tmp_dir} = .claude/tmp/review-respond-{timestamp}/
{tmp_dir}/triage.json          ← output of the triage sub-agent
{tmp_dir}/estimates/{id}.json  ← output of the estimate sub-agents (one file per finding)
{tmp_dir}/statuses/{id}.json   ← output of the fix sub-agents (one file per finding)

Each sub-agent obtains finding-body information such as description / location / existing metadata directly by Read-ing around the METADATA marker in the review document, keyed by id.

events.jsonl

The final markdown reflection still uses {basename}.events.jsonl next to the markdown file (e.g. review-round1.md → review-round1.events.jsonl, hereafter {events_path}). events.jsonl is generated by the aggregator sub-agent, which reads files under {tmp_dir}/ and emits them in one pass. Format:

{"id":"C-1","field":"triage","value":"🔧 Will Fix (assignee: cpp-sensei) — reason"}
{"id":"C-1","field":"estimate","value":"▶️ Maintain — Cost: M, Future: S, Signals: b,d"}
{"id":"C-1","field":"status","value":"🟢 Fixed — fix description"}

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

Creating the working directory

At the start of Step 1, the leader (you) creates {tmp_dir} with mkdir -p {tmp_dir}/estimates {tmp_dir}/statuses and passes {tmp_dir} to each sub-agent.

Step 1 — Triage (delegate to the triage sub-agent)

Delegate triage to a single sub-agent that is separate from the specialist agents who will perform the fixes (to isolate bias). The triage Sub reads the review document directly, extracts findings, and performs stage classification and triage decisions in a single pass. Make it Write the result to a file; do not load the decision body into the leader's context.

Launch procedure:

1. Launch the sub-agent with Agent(subagent_type="general-purpose", prompt=...). Do not specify the model (use the agent definition's default). Task-specific instructions are stored in the templates/triage.md external template. Example launch prompt:

As your first action, you MUST Read `.claude/skills/review-respond/templates/triage.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}
- tmp_dir: {tmp_dir}
- previous_round_doc_paths: {previous_round_doc_paths} (in the standard flow, "(none)". Non-empty only when an upper flow such as review-rounds passes a list of past-round doc_paths.)

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 sub-agent ({path, will_fix_count, wontfix_count, by_stage, by_assignee, template_id}). Do not load the triage body.
3. Verify that template_id matches 1e9c4f7a-5b82-4d63-a1c8-3f7d2e9b4a15. On mismatch, relaunch the sub-agent.
4. Present the triage summary (counts) to the user. Read {tmp_dir}/triage.json only when details are needed (typically unnecessary).

When will_fix_count == 0, skip Steps 2/3/4 and proceed to Step 5 (compile).

Step 2 — Estimate (parallel delegation to specialist sub-agents)

Loop over the by_assignee array received in Step 1. For each {assignee, ids}, launch a specialist sub-agent in parallel via Agent(subagent_type=assignee, prompt=...) (the agent definition's persona and specialty perspective load automatically). Each sub-agent estimates its assigned ids in a batch and Writes {tmp_dir}/estimates/{id}.json per id.

Launch procedure:

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

As your first action, you MUST Read `.claude/skills/review-respond/templates/estimate.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.

2. Receive the return value from every estimate agent ({items: [{id, verdict}, ...], template_id}). Verify that each agent's template_id matches 8b2d5f1c-7a93-4e64-b8d1-2c5e9a3f7b48; on mismatch, relaunch that agent. Aggregate items to build a {id → verdict} map. Do not load the estimate body. Each agent has Written {tmp_dir}/estimates/{id}.json. The leader keeps the {id → verdict} map in context for selecting the fix targets in Step 3.

3. Launch the aggregator sub-agent via Agent(subagent_type="review-helper", prompt=...) to generate the estimate result summary. The aggregator sub-agent always produces an integrated summary (a single table merging review + triage + estimate, plus a link to the review document).

   Example launch prompt for the aggregator sub-agent. Task-specific instructions are stored in the templates/estimate-summary.md external template:

   As your first action, you MUST Read `.claude/skills/review-respond/templates/estimate-summary.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}
   
   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 aggregator sub-agent ({summary_path, summary_line, maintain_count, downgrade_count, alternative_count, template_id}). Verify that template_id matches 5c1e9b7a-3d48-4a96-b8e2-7f3c5a1d4b29; on mismatch, relaunch the sub-agent. The leader keeps only summary_line in context and does not load the table body.

4. In confirm mode, Read summary_path, present it to the user, and wait for user confirmation before proceeding to the fix step. In no-confirm mode, do not Read summary_path (to avoid bloating the leader's context). Confirm-mode determination: review-respond standalone is confirm mode when --no-confirm is not specified, and no-confirm mode when specified. When an upper orchestrator (review-rounds, etc.) takes on the role, follow that orchestrator's confirmation flag.

When both Maintain and Alternative are 0 (all Downgrade): skip Steps 3 and 4 and proceed to Step 5 (compile). Record them as Downgrade in the summary.

Step 3 — Fix (parallel delegation to specialist sub-agents)

Cross-reference the by_assignee from Step 1 with the {id → verdict} map from Step 2. Extract only the ids whose verdict is Maintain or Alternative, and re-group them by assignee. For each {assignee, ids}, launch a fix sub-agent via Agent(subagent_type=assignee, prompt=...) (the agent definition's persona and specialty perspective load automatically).

Agent launch prompt

Task-specific instructions are stored in the templates/fix.md external template. Pass the following to each fix agent (do not include the persona):

As your first action, you MUST Read `.claude/skills/review-respond/templates/fix.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.

Parallelization (per assignee)

• Different assignees launch in parallel.
• Handling of ids within the same assignee follows the parallelization constraint in the prompt above (the specialist Sub itself decides).

Save status to intermediate files

Receive the return value from every fix agent ({items: [{id, path}, ...], template_id}). Verify that template_id matches 2f8a1c5d-7b94-4e63-a1c8-5d3f9b2e7a14; on mismatch, relaunch that agent. The leader only collects items; do not load the status body into context.

Step 4 — Format verification & build verification

The leader (you) does not run the formatter or build commands directly and does not read source code. The format & build verification Sub performs only a single pass of format and build. On build failure, it reads the code, identifies the responsible specialist, and returns the result (it does not fix the code itself). The leader sees the result, launches a specialist Sub to perform the fix, and orchestrates a loop that alternately relaunches the format & build verification Sub and the specialist Sub until the build passes.

Loop control (leader)

Maximum attempts: 5

The leader repeats the following up to the maximum attempts:

1. Launch the format & build verification Sub via Agent(subagent_type="review-helper", prompt=...) (see "Format & build verification Sub launch prompt" section for the prompt). The Sub runs format → build once and, on failure, identifies the specialist.
2. Receive the return value from the Sub ({path, success, format_violations_fixed, summary_line, template_id}). Verify that template_id matches 9d3c5f8a-2b71-4e94-a8c5-1f7d3b9e2c46; on mismatch, relaunch the Sub.
3. If success == true, exit the loop (success).
4. If success == false: a. Read {tmp_dir}/format-build-result.json and obtain suggested_specialist / error_summary / error_files / fix_guidance / build_log_path (build error info is operational data, not decision body, so loading it into context is allowed; do not Read source code itself). b. Launch the build-fix specialist Sub via Agent(subagent_type=suggested_specialist, prompt=...) (the agent definition's persona and specialty perspective load automatically; see "Build-fix specialist Sub launch prompt" section for the prompt). c. Receive the return value from the build-fix specialist Sub ({description, template_id}) and verify that template_id matches 6e2a9f5c-1d83-4b74-9c2e-5a8d3f1b7e29; on mismatch, relaunch that Sub. d. After the fix, return to the top of the loop (rerun the format & build verification Sub starting from format; format must be rechecked because code has changed).
5. If the build still fails after reaching the maximum attempts, present error_summary to the user, exit the loop, and proceed to Step 5 (compile Sub).

Format & build verification Sub launch prompt

Task-specific instructions are stored in the templates/format-build-verify.md external template.

As your first action, you MUST Read `.claude/skills/review-respond/templates/format-build-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):
- tmp_dir: {tmp_dir}
- attempt_num: {attempt_num}

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

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

Build-fix specialist Sub launch prompt

Do not include the persona (the agent definition is loaded via subagent_type). Task-specific instructions are stored in the templates/build-fix.md external template.

As your first action, you MUST Read `.claude/skills/review-respond/templates/build-fix.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}

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

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

Step 5 — Reflect into the review document (delegate to the aggregator sub-agent)

The leader (you) does not load decision bodies into 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-respond/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. The leader receives the return value ({events_path, fixed_count, code_changed, summary_line, template_id}). Verify that template_id matches 3b7f1c5d-8a29-4e63-b1c8-9d3a7f5e2b41; on mismatch, relaunch the sub-agent.

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

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

Step 6 — Summary

The leader prints the summary_line received from the aggregator sub-agent to the console. Only when a detailed table is needed, Read the updated {document_path} and present it following the .claude/skills/review-respond/templates/respond-summary.md format (typically the summary line is sufficient).