Goldfish Review: Loop (Orchestration Driver)
When running in Codex or ChatGPT Work, first read Codex integration.
In Claude Code or Cowork, read ${CLAUDE_PLUGIN_ROOT}/docs/claude.md first.
Overview
This skill acts as the central orchestration engine driving the multi-agent
review loop. It coordinates two distinct agent memory models:
- The Goldfish (Adversarial Auditors): Subagents spawned in isolated,
fresh context windows to catch unstated assumptions without historical bias.
- The Elephant (Persistent Resolver): The primary agent context holding
institutional knowledge to evaluate findings and apply approved repairs.
The driver manages argument intake, resolves paths for reviewers and standards,
unconditionally re-parses target line ranges before every iteration, spawns
concurrent specialized Goldfish auditors based on configuration, and coordinates
with the Elephant context to resolve findings.
Delegation
A Goldfish runs in a fresh context with no conversation history. Spawn each
subagent with your harness's subagent tool (Antigravity: invoke_subagent; Claude Code: Agent; Codex: spawn_agent). Each subagent is defined in agents/<file>.md, and its
frontmatter name (for example egm-zoom-out) is the subagent type to request
where your harness registers named subagents. Otherwise spawn a general-purpose
subagent and tell it to read that persona file first. Pass the prompt verbatim
and wait for the report. If your harness cannot nest subagents,
use direct dispatch instead of the synthesizer. See docs/harnesses.md.
If your harness has no subagent tool, stop and tell the user: a review in the same
context is not a Goldfish review.
Inputs
The caller or user provides exactly these parameters:
TargetFile: Absolute or relative path to target document.
SemanticTarget: Descriptive targeting string (e.g., "Target the H4
block with SS-ID 'S1.12'"), or full file.
Reviewers: List of reviewer names (shortnames or paths).
Standards: Mapping of reviewer names to standard names (shortnames or
paths).
GoldfishContext: A reading list (source files, directories, or
documentation URLs) fed to reviewers to establish their baseline. An empty
list from the caller counts as provided; do not ask for it again. Some
reviewers cannot open URLs, so before the first round save the raw page of
each URL as a new file in the working directory (or your harness's artifact
directory) and pass its absolute path instead. If a page cannot be saved,
ask the user for a local copy and end your turn; if no one can answer,
as in a headless run, leave it out, tell the user, and keep going.
Path & Standard Resolution Logic
When resolving names in Reviewers and Standards:
- Reviewer Shortnames: Map reviewer shortname (e.g.,
design_critic,
structural, style, implementation_readiness,
codebase_details, comprehension, zoom_out) to agents/{name}.md.
The persona file defines the reviewer's core mandates, audit vectors, and
output format.
- Standard Shortnames: Map standard shortname (e.g.,
feature-spec-standard,
implementation-readiness-standard, zoom-out-standard, heilmeier-standard,
re-implementation-standard) to resources/document_standards/{name}.md.
- Custom Paths: If the name contains a slash (
/), treat it as an
absolute or workspace-relative path and read it directly.
Execution Workflow
Step 1: Intake & Configuration UX
Evaluate the provided inputs (TargetFile, SemanticTarget, Reviewers,
Standards, GoldfishContext).
- Identify Missing Inputs: Determine which of the required parameters are
missing.
- Interactive Onboarding:
- If all inputs are present, proceed to Step 2.
- If some or all inputs are missing, interactively prompt the user
only for the missing inputs, one at a time via chat messages.
- Reviewer Recommendations:
- Feature Specs: Recommend
design_critic (mapped to
resources/document_standards/feature-spec-standard.md) and
structural (mapped to resources/document_standards/feature-spec-standard.md).
- Implementation Plans: Recommend
implementation_readiness
(mapped to resources/document_standards/implementation-readiness-standard.md)
and codebase_details.
- Confirm Configuration: Display the consolidated plan (Target, Reviewers,
and mapped Standards) and ask the user to confirm before proceeding.
Step 2: The Sharpening Loop (Iterative Cycle)
Execute the following sequence in a continuous loop:
2.1 Unconditional Target Resolution
Before every iteration, unconditionally re-scan TargetFile by reading it
and using the stable SemanticTarget string (e.g., locating the target header) to
dynamically determine the updated absolute start and end line numbers. This
ensures absolute accuracy even if the file was edited in prior rounds. (If full file mode is specified, confirm full-file line bounds).
2.2 Review Swarm Execution
- Launch Subagent Swarm:
Spawn subagents to execute the review:
- Hierarchical Dispatch (Synthesizer): Spawn the intermediate
synthesizer subagent (
agents/synthesizer.md / egm-synthesizer).
The synthesizer spawns the Goldfish review swarm in
parallel, deduplicates findings, writes the report artifact, and
returns a single summary message to avoid context pollution in the root
conversation. Pass it the Failed Reviewers rule below and
GoldfishContext, and tell it to give those files to each reviewer.
Its summary must give a status, completed or not run, for each
requested reviewer.
- Direct Dispatch (Flat Swarm): Alternatively, spawn each requested
reviewer subagent in
Reviewers directly.
Instruct each subagent to first read its persona definition in
agents/{name}.md, then audit TargetFile at the resolved line range
against its designated standard in resources/document_standards/,
supplying GoldfishContext.
- Each reviewer produces findings with severity (🔴 Blocker, 🟡 Major, 🟢
Nit), line numbers, discrepancy descriptions, and rationales.
- Consolidate Findings: Collect all findings across reviewers into a single
flat
FindingsList. Give each finding a stable id
(<reviewer>-<round>-<n>) and record its reviewer, severity, and affected
scope.
- Failed Reviewers: A reviewer that times out, fails, or returns no report
did not review. Retry it once. If it fails again, record it as not run
in the report. Never count it as a reviewer with zero findings. If the
synthesizer summary has no status for a requested reviewer, record that
reviewer as not run.
2.3 Aggregated Resolution Hand-off
- Pass
TargetFile, the active line range, and the aggregated FindingsList
to the egm-resolve workflow.
- Execute the resolution workflow in the primary Elephant context:
- Categorize findings into
CONTEST vs. PROPOSE FIX.
- Save
goldfish_review_report.md with your file-writing tool.
- Present the interactive decision gate (Auto accept, Continue, Interactive
breakdown).
- Apply approved text repairs to
TargetFile using your file-editing tool.
2.4 Iteration Check & Turn Boundary
Fresh reviewers sample differently each round, so a round with zero findings
is rare even when the document improves. Use these rules instead:
- Settled findings: A finding is settled when it is contested or
recorded without a fix (accepted risk). Keep the settled list across
rounds. If a new reviewer raises a settled finding again (same affected
scope, same issue), do not re-open it.
- Fixed findings: An applied fix does not settle a finding. If a later
reviewer raises the same issue at the same scope, the fix failed or a
later edit reintroduced the issue. Re-open the finding.
- Clean round: A round is clean when no reviewer raises a Blocker or
Major finding that is not settled. Nits do not block. A reviewer recorded
as not run makes the round not clean. Decide this from the review results,
before you apply the fixes of that round.
- Converged: Two consecutive clean rounds. One clean round is not enough,
because the next fresh reviewer can find a different gap in the same text.
- Cap: 5 rounds.
- Churn: A new finding is at the scope of an applied fix, and reverting
that fix would resolve it.
On converged, go to Step 3. On cap or churn, write a short list of the open
findings by severity, then ask the user one question: accept and proceed,
continue past the cap, or return the document to drafting.
Crucial Turn-Taking Requirement: After the resolution phase finishes for a
given round, the loop driver MUST respect the turn-taking checkpoint in
egm-resolve. The driver must remain idle across human turns,
only looping back to Step 2.1 when the user explicitly confirms they wish to run
another round of review.
Step 3: Output Boundary & Final Checkpoint
Upon completion (converged, cap or churn accepted by the user, or manual
halt):
- Programmatic Callers: If running as a subflow of
egm-review, exit
cleanly to hand execution back to the parent workflow.
- Manual Invocations: Output a summary of completion in chat: "The review
loop has completed after [N] rounds ([converged | accepted at cap | halted]).
Open findings are in the report. Would you like to proceed to
the next stage, or do you have any final questions?"
1---2name: egm-review-loop3license: Apache-2.04disable-model-invocation: true5description: >-6 Executes the Antagonistic-Review process from the Elephant-Goldfish7 Model (EGM) via an automated multi-agent review loop to audit documents8 against qualitative standards and structural templates, and automatically9 apply approved fixes. Use when reviewing design docs, READMEs, feature10 specifications, implementation plans, or verifying document completeness11 and tone.12metadata:13 source: https://skillmd.com/skills/google/egm-review-loop14---1516# Goldfish Review: Loop (Orchestration Driver)1718When running in Codex or ChatGPT Work, first read [Codex integration](../../docs/codex.md).19In Claude Code or Cowork, read `${CLAUDE_PLUGIN_ROOT}/docs/claude.md` first.2021## Overview2223This skill acts as the central orchestration engine driving the multi-agent24review loop. It coordinates two distinct agent memory models:2526* **The Goldfish (Adversarial Auditors)**: Subagents spawned in isolated,27 fresh context windows to catch unstated assumptions without historical bias.28* **The Elephant (Persistent Resolver)**: The primary agent context holding29 institutional knowledge to evaluate findings and apply approved repairs.3031The driver manages argument intake, resolves paths for reviewers and standards,32unconditionally re-parses target line ranges before every iteration, spawns33concurrent specialized Goldfish auditors based on configuration, and coordinates34with the Elephant context to resolve findings.3536## Delegation3738A Goldfish runs in a fresh context with no conversation history. Spawn each39subagent with your harness's subagent tool (Antigravity: `invoke_subagent`; Claude Code: `Agent`; Codex: `spawn_agent`). Each subagent is defined in `agents/<file>.md`, and its40frontmatter `name` (for example `egm-zoom-out`) is the subagent type to request41where your harness registers named subagents. Otherwise spawn a general-purpose42subagent and tell it to read that persona file first. Pass the prompt verbatim43and wait for the report. If your harness cannot nest subagents,44use direct dispatch instead of the synthesizer. See `docs/harnesses.md`.45If your harness has no subagent tool, stop and tell the user: a review in the same46context is not a Goldfish review.4748## Inputs4950The caller or user provides exactly these parameters:5152* **`TargetFile`**: Absolute or relative path to target document.53* **`SemanticTarget`**: Descriptive targeting string (e.g., *"Target the H454 block with SS-ID 'S1.12'"*), or `full file`.55* **`Reviewers`**: List of reviewer names (shortnames or paths).56* **`Standards`**: Mapping of reviewer names to standard names (shortnames or57 paths).58* **`GoldfishContext`**: A reading list (source files, directories, or59 documentation URLs) fed to reviewers to establish their baseline. An empty60 list from the caller counts as provided; do not ask for it again. Some61 reviewers cannot open URLs, so before the first round save the raw page of62 each URL as a new file in the working directory (or your harness's artifact63 directory) and pass its absolute path instead. If a page cannot be saved,64 ask the user for a local copy and end your turn; if no one can answer,65 as in a headless run, leave it out, tell the user, and keep going.6667## Path & Standard Resolution Logic6869When resolving names in `Reviewers` and `Standards`:7071* **Reviewer Shortnames**: Map reviewer shortname (e.g., `design_critic`,72 `structural`, `style`, `implementation_readiness`,73 `codebase_details`, `comprehension`, `zoom_out`) to `agents/{name}.md`.74 The persona file defines the reviewer's core mandates, audit vectors, and75 output format.76* **Standard Shortnames**: Map standard shortname (e.g., `feature-spec-standard`,77 `implementation-readiness-standard`, `zoom-out-standard`, `heilmeier-standard`,78 `re-implementation-standard`) to `resources/document_standards/{name}.md`.79* **Custom Paths**: If the name contains a slash (`/`), treat it as an80 absolute or workspace-relative path and read it directly.8182## Execution Workflow8384### Step 1: Intake & Configuration UX8586Evaluate the provided inputs (`TargetFile`, `SemanticTarget`, `Reviewers`,87`Standards`, `GoldfishContext`).88891. **Identify Missing Inputs**: Determine which of the required parameters are90 missing.912. **Interactive Onboarding**:92 * If **all** inputs are present, proceed to Step 2.93 * If **some or all** inputs are missing, interactively prompt the user94 **only for the missing inputs**, one at a time via chat messages.953. **Reviewer Recommendations**:96 * *Feature Specs*: Recommend `design_critic` (mapped to97 `resources/document_standards/feature-spec-standard.md`) and98 `structural` (mapped to `resources/document_standards/feature-spec-standard.md`).99 * *Implementation Plans*: Recommend `implementation_readiness`100 (mapped to `resources/document_standards/implementation-readiness-standard.md`)101 and `codebase_details`.1024. **Confirm Configuration**: Display the consolidated plan (Target, Reviewers,103 and mapped Standards) and ask the user to confirm before proceeding.104105### Step 2: The Sharpening Loop (Iterative Cycle)106107Execute the following sequence in a continuous loop:108109#### 2.1 Unconditional Target Resolution110111Before every iteration, unconditionally re-scan `TargetFile` by reading it112and using the stable `SemanticTarget` string (e.g., locating the target header) to113dynamically determine the updated absolute start and end line numbers. This114ensures absolute accuracy even if the file was edited in prior rounds. (If `full115file` mode is specified, confirm full-file line bounds).116117#### 2.2 Review Swarm Execution1181191. **Launch Subagent Swarm**:120 Spawn subagents to execute the review:121 * **Hierarchical Dispatch (Synthesizer)**: Spawn the intermediate122 synthesizer subagent (`agents/synthesizer.md` / `egm-synthesizer`).123 The synthesizer spawns the Goldfish review swarm in124 parallel, deduplicates findings, writes the report artifact, and125 returns a single summary message to avoid context pollution in the root126 conversation. Pass it the Failed Reviewers rule below and127 `GoldfishContext`, and tell it to give those files to each reviewer.128 Its summary must give a status, `completed` or `not run`, for each129 requested reviewer.130 * **Direct Dispatch (Flat Swarm)**: Alternatively, spawn each requested131 reviewer subagent in `Reviewers` directly.132 Instruct each subagent to first read its persona definition in133 `agents/{name}.md`, then audit `TargetFile` at the resolved line range134 against its designated standard in `resources/document_standards/`,135 supplying `GoldfishContext`.136 * Each reviewer produces findings with severity (🔴 Blocker, 🟡 Major, 🟢137 Nit), line numbers, discrepancy descriptions, and rationales.1382. **Consolidate Findings**: Collect all findings across reviewers into a single139 flat `FindingsList`. Give each finding a stable id140 (`<reviewer>-<round>-<n>`) and record its reviewer, severity, and affected141 scope.1423. **Failed Reviewers**: A reviewer that times out, fails, or returns no report143 did not review. Retry it once. If it fails again, record it as **not run**144 in the report. Never count it as a reviewer with zero findings. If the145 synthesizer summary has no status for a requested reviewer, record that146 reviewer as not run.147148#### 2.3 Aggregated Resolution Hand-off1491501. Pass `TargetFile`, the active line range, and the aggregated `FindingsList`151 to the **`egm-resolve`** workflow.1522. Execute the resolution workflow in the primary Elephant context:153 * Categorize findings into `CONTEST` vs. `PROPOSE FIX`.154 * Save `goldfish_review_report.md` with your file-writing tool.155 * Present the interactive decision gate (Auto accept, Continue, Interactive156 breakdown).157 * Apply approved text repairs to `TargetFile` using your file-editing tool.158159#### 2.4 Iteration Check & Turn Boundary160161Fresh reviewers sample differently each round, so a round with zero findings162is rare even when the document improves. Use these rules instead:163164* **Settled findings**: A finding is settled when it is contested or165 recorded without a fix (accepted risk). Keep the settled list across166 rounds. If a new reviewer raises a settled finding again (same affected167 scope, same issue), do not re-open it.168* **Fixed findings**: An applied fix does not settle a finding. If a later169 reviewer raises the same issue at the same scope, the fix failed or a170 later edit reintroduced the issue. Re-open the finding.171* **Clean round**: A round is clean when no reviewer raises a Blocker or172 Major finding that is not settled. Nits do not block. A reviewer recorded173 as not run makes the round not clean. Decide this from the review results,174 before you apply the fixes of that round.175* **Converged**: Two consecutive clean rounds. One clean round is not enough,176 because the next fresh reviewer can find a different gap in the same text.177* **Cap**: 5 rounds.178* **Churn**: A new finding is at the scope of an applied fix, and reverting179 that fix would resolve it.180181On converged, go to Step 3. On cap or churn, write a short list of the open182findings by severity, then ask the user one question: accept and proceed,183continue past the cap, or return the document to drafting.184185**Crucial Turn-Taking Requirement**: After the resolution phase finishes for a186given round, the loop driver **MUST respect the turn-taking checkpoint in187`egm-resolve`**. The driver must remain idle across human turns,188only looping back to Step 2.1 when the user explicitly confirms they wish to run189another round of review.190191### Step 3: Output Boundary & Final Checkpoint192193Upon completion (converged, cap or churn accepted by the user, or manual194halt):195196* **Programmatic Callers**: If running as a subflow of `egm-review`, exit197 cleanly to hand execution back to the parent workflow.198* **Manual Invocations**: Output a summary of completion in chat: *"The review199 loop has completed after [N] rounds ([converged | accepted at cap | halted]).200Open findings are in the report. Would you like to proceed to201 the next stage, or do you have any final questions?"*