Review Claude Code's plan first: the EGM kit and the skip-or-review checklist

TL;DR and verdict

The agent that wrote your plan cannot see its holes. EGM, the Elephant-Goldfish Model, is Google's free plugin for Claude Code that fixes this: the elephant writes the plan with you, and goldfish reviewers with no memory of the conversation read only the plan and your code. It is not an officially supported Google product s25.

We ran it on one real feature of a family gift-list app (Next.js, Notion as the database): let a relative reserve a gift so two people never buy the same one, with the parents unable to see who reserved what. On a copy of the repo, never the real list.

The planner named the race itself. The reviewers found two holes nobody in the conversation had raised: the parents could work out who reserved what from their own hosting logs, and a saved cookie could be replayed to cancel someone else's reservation.
The review's fix for the race weakened the goal. We contested it, and the design changed.
A fresh session built the feature to the approved design: 216 tests, and 30/30 races on the last unit gave exactly one winner. That ran against a stand-in for Notion, so the real check is still ours to run.
On a one-line README fix, the plain workflow cost $0.0455 and 10 s. The EGM path for the feature cost $7.10 and 32 min before any code.

Verdict: run the review when a mistake touches someone else's data, privacy, permissions or money. Skip it for a small, clear fix. The pack below gives you the install, the one CLAUDE.md line, a cheat sheet and the checklist.

Sourced synthesis

What EGM is. Google's README says thousands of Google engineers use it to draft specs with deep-context agents and stress-test them with zero-context subagents before writing code s1. That is Google's own claim, with no count. The idea comes from Dave Rensin, who wrote "We are mass-producing our mistakes" if we are not careful s7. The only release so far is v0.1.0, published 2026-10-27 s26. It is Apache-2.0 and "not an officially supported Google product" s25 s9.

Install is two commands and a new session. claude plugin marketplace add google/elephant-goldfish-model, then claude plugin install egm@egm, then start a new session s1 s2. Others report the same two commands s6 s8. We added --scope project to the install, so it applies to that repo only. It needs Claude Code 2.1.271 or later for omitClaudeMd support s2. Our version was 2.1.294.

Why the reviewers are blind. Normal subagents exclude the parent conversation. omitClaudeMd also excludes the user, project and local instruction files s2. The reviewer adapters declare tools: [Read, Grep, Glob], model: inherit and omitClaudeMd: true s20. The synthesizer is different: it spawns reviewers, with nesting allowed up to 3 levels s2. The docs add a caveat: this is "context and tool isolation, not filesystem isolation: reviewers can read accessible files" s2.

One CLAUDE.md line keeps the reports in a folder. Without it, review files accumulate at the repository root, where you can commit them by mistake s23. A line EGM artifact directory: <path> in CLAUDE.md or AGENTS.md sends them to that folder s2.

The workflow.

Brainstorm spawns a 6-lens goldfish swarm and writes concepts_brief.md s21.
Draft writes design_draft.md s22.
Review runs five phases: Initial Zoom Out Review, Comprehension Review, Design Critique, Intermediate Zoom Out Review and Implementation Readiness s3.
Resolve labels each issue CONTEST, ESCALATE, PROPOSE FIX or DECLINE. You choose, and "auto accept" batch-applies the proposed fixes, skipping contested items s24.

What other people found. A field report on Claude Code and EGM 0.1.0 counted 26 findings (9 blockers, 9 major, 8 nits), 20 fixed, 4 skipped, 2 wrong, about $3.40 of usage at API prices and 24 of 24 tests passing on the first try. Its own lesson: "Goldfish read documents. They don't run code." s6. Rensin says about 30% of the suggestions are highly valuable, which he calls more than enough s7.

And what says to skip it. The README: for a small, clear bug fix, use your normal coding workflow s25. The FAQ: design and review "may not pay off for a small, well-understood change", and completing the workflow alone "does not demonstrate a productivity improvement" s4. A co-builder would try it on background jobs, permissions, data changes or a new service boundary s10. A small pilot (three runs per arm) found EGM "added nothing over the plain plan, at about five times the cost" s5. We cite it as one small pilot, not a rule.

Why the race is real. The Notion docs offer no atomic increment or conditional write for a property, and writes replace the whole value s27. Two relatives who read the same count can both write, and one reservation is lost.

Our own run, verbatim. These figures are ours, not from a source above. Session model Claude Sonnet 5.5, and the reviewers inherit it. Costs are API-equivalent on Sonnet 5.5.

The full review ran 9 reviewer subagents in 5 sequential stages, and the consolidated turn took 7 min 24 s. Raw findings across the five stages: 77. Consolidated into 12 action items, with 1 Blocker.
Resolve produced 37 issues: 4 ESCALATE, 5 CONTEST, 2 DECLINE, 26 PROPOSE FIX. It checked the reviewers against the code first and found one wrong finding: a reviewer said input.tsx became unused, but the login page still imports it.
The review's fix direction for the race was to drop the goal. We contested it. The design that gave one winner came from that contest, and no reviewer ever read it.
Build from the approved design in a fresh session: 216 tests passed, and the race test on the last unit gave one success and one "full" in 30 of 30 seeds.
Cost: $7.10 and 32 min of model time before any code (brainstorm, draft, review, resolve). The README fix on a copy without EGM: $0.0455 and 10 s.

Code

Five reference files. The first four you copy into your repo or keep open. The fifth is the real report from our run, so you can see what the output looks like.

1. Install and uninstall. Run it from your project folder, then start a new session.

egm-install.sh

#!/usr/bin/env bash
# Install Google's EGM plugin for this project only.
# Needs Claude Code 2.1.271 or later (the reviewers rely on omitClaudeMd).
claude plugin marketplace add google/elephant-goldfish-model
claude plugin install egm@egm --scope project

# Start a new Claude Code session now, so the plugin loads.
# The commands then show up with the /egm: prefix.

# Uninstall (run from the same project folder):
# claude plugin uninstall egm@egm --scope project
# claude plugin marketplace remove egm

egm-install.sh on GitHub

2. The CLAUDE.md line. Add it to your project's CLAUDE.md so the reports land in docs/egm.

CLAUDE.md

<!-- Keeps EGM reports in one folder instead of the repo root. Create docs/egm or let EGM create it. -->
EGM artifact directory: docs/egm

CLAUDE.md on GitHub

3. The review cheat sheet. The commands in order, the five stages and their report files, what resolve's labels mean, and the reviewer settings.

egm-review-cheatsheet.md

# EGM review cheat sheet

## The commands, in order

1. `/egm:egm-brainstorm <the feature in one sentence>` writes `concepts_brief.md`.
2. `/egm:egm-draft` writes the design document, one section at a time. You approve each section.
3. `/egm:egm-review <design>` runs the five review stages (below). Pick the consolidated mode to get one merged list.
4. `/egm:egm-resolve` turns the reports into one table of issues. You answer each one.
5. Open a fresh session and send:

```
Build the feature exactly to the approved design in docs/egm/<file>.md; add tests.
```

## The five review stages and their report files

| Stage | What it asks | Report file |
|---|---|---|
| 1. Initial Zoom Out Review | Does the design solve the right problem? | `zoom_out_report.md` |
| 2. Comprehension Review | Would a newcomer understand it? | `comprehension_report.md` |
| 3. Design Critique | Attacks the design, its structure and its wording | `critic_report.md` |
| 4. Intermediate Zoom Out Review | Zooms out again on the unedited design | `intermediate_zoom_out_report.md` |
| 5. Implementation Readiness | Checks each step against your real code | `implementation_readiness_report.md` |

The consolidated mode also writes `consolidated_review_report.md`. Resolve writes `goldfish_review_report.md`.

## What resolve's suggestions mean

- ESCALATE: the reviewers found a decision only you can make.
- CONTEST: the agent thinks the finding is wrong or the fix is too weak, and says why. You can still overrule it.
- DECLINE: the agent proposes not acting on the finding.
- PROPOSE FIX: the agent proposes an edit to the design.
- "auto accept": reply with these two words to batch-apply every PROPOSE FIX and skip CONTEST items. Decide the escalated issues first.

## Reviewer settings (Claude adapters)

```
tools: [Read, Grep, Glob]
model: inherit
omitClaudeMd: true
```

Read-only tools, the same model as your session, and no CLAUDE.md or other instruction files. This is context and tool isolation, not filesystem isolation: reviewers can read accessible files.

## Before you build

Reviewers read documents. They do not run code. If your design relies on an outside service behaving a certain way, run a check against a copy of the real thing before you ship.

egm-review-cheatsheet.md on GitHub

4. The skip-or-review checklist. Read it before you type the build prompt.

skip-or-review.md

# Skip or review

Ask one question before you type the build prompt: if this is wrong, whose data, privacy, permissions or money does it touch?

## Run the EGM review when the change involves

- [ ] Data that several people write at the same time
- [ ] Privacy: something someone must not be able to see or work out
- [ ] Permissions: who can do, change or cancel what
- [ ] Money: a charge, a price, a balance, a refund
- [ ] A time rule, a background job or a new service boundary

## Use your normal workflow when

- [ ] The fix is small and clear and you can say it in one sentence
- [ ] You could one-shot it
- [ ] A wrong result is visible at once and costs nothing to undo

## What the README says

> Use it when a feature needs design decisions before implementation. For a small, clear bug fix, use your normal coding workflow.

## What the FAQ adds

> Design and review take time and may not pay off for a small, well-understood change.

> Completing the EGM workflow alone does not demonstrate a productivity improvement.

skip-or-review.md on GitHub

5. A real consolidated report. This is the report from our run on a family gift-list app. Note how every action item points back to the stage findings behind it.

example-consolidated-report.md

<!-- The consolidated review report from our run on a family gift-list app. -->

# Consolidated Review Report

**Target:** `docs/egm/gift-reservations.md` (464 lines; FeatureRange 1-280, DetailedRange 281-464)
**Mode:** Consolidated report, all five stages, no checkpoints. No edits were applied to the document.
**Stage reports:** `zoom_out_report.md` (5), `comprehension_report.md` (6), `critic_report.md` (7), `intermediate_zoom_out_report.md` (8), `implementation_readiness_report.md` (9).

**Overall:** The design fits the problem and keeps Notion as the only store. It is not ready to implement. Five issues need decisions from the author, and the plan has errors a reader can check against the code: a build that breaks mid-sequence, a wrong HTTP status, and a wrong assumption about SDK retries.

## Blockers
Stage 8 raised one item to Blocker (A1). Stages 5, 6, 7 and 9 report none.

## Action items by priority

### 🔴 Blocker

**A1. Decide whether to drop the post-write re-read.** (Stage 5 ZO-2, Stage 6 CO-3/CO-6, Stage 7 CR-1/CR-2/CR-3/CR-8, Stage 8 Z8-1, Stage 9 IR-6)
Lines 28, 132-134, 159, 174, 220, 276, 360, 366, 415.
The re-read does not catch the main race (the document says so at line 174), assumes read-after-write consistency with no evidence, checks only `x`, adds a third Notion call, and leaves the cookie and response behaviour undefined when it fails. Goal 2 and the rejection of Alternative F rest on it. Stage 8 recommends removing it, along with `changed_meanwhile` and the "unverified" branch, rewriting Goal 2 as "reduces duplicate purchases, does not prevent them" and rewriting Alternative F around the real trade-off. If kept, every post-write failure needs a stated cookie and response behaviour. Decide this first: it closes or removes about eight other findings.

### 🟡 Major: design and scope

**A2. Fix the cookie's stated guarantees and the stale-record dead end.** (CR-4, CR-5, Z8-2, Z8-3, ZO-5)
Lines 32, 34, 85, 111, 114, 144-148, 246-250, 355.
A saved copy of the cookie can be replayed to cancel someone else's unit, and clearing the cookie bypasses the one-unit and 80-id limits. After the parents release a unit by hand, the stale cookie makes reserve fail with 409 `already_reserved`. State the real threat model (stops accidental cancels and casual tampering among about 30 relatives), and decide whether to keep the `already_reserved` guard and the 80-id cap.

**A3. Qualify "no identity is stored or logged", and decide on the bespoke log line.** (CR-6, Z8-4, CO-7)
Lines 29, 37, 270-271, 367.
Vercel request logs and Notion edit history, together with timestamped log lines, can let the parents correlate who reserved what. The log line is also specified three different ways.

**A4. Settle where configuration is checked, and the effect on the list route.** (ZO-4, Z8-5, CR-17, CO-12, IR-13)
Lines 36, 115, 117, 168, 394-395, 403.
The proxy 503 for `/api/registry*` changes the existing list GET route, which the plan doesn't list. Configuration is checked in the proxy, the routes and `canReserve`. The 401 versus 503 precedence is unspecified.

**A5. Reuse the existing HMAC helper.** (ZO-1, IR-8)
Lines 111, 324. `src/lib/auth.ts` already has `hmacBase64Url`. The plan writes a second implementation and leaves the crypto details (key import, base64url without `Buffer`, signed text) unspecified.

### 🟡 Major: factual errors and unstated assumptions

**A6. "Each step leaves the project building" is false.** (CO-2, IR-1, Z8-6)
Line 283. The build is red from item 8 through item 16. Group the changes into one landing phase or keep the old exports until the consumers go.

**A7. The deleted `PATCH` route returns 404, not 405.** (CO-5, CR-7, IR-2)
Lines 116, 181, 388, 458. Correct the claim and manual test 7. A 410 stub is an option, but Stage 8 advises against adding code for it.

**A8. Handler signatures ignore Next 16 async APIs.** (IR-3)
Lines 115, 378, 382, 402. `params` is a `Promise`, and `cookies()` is async.

**A9. The Notion SDK already retries 429s, and error classification is unspecified.** (IR-4, IR-5)
Lines 276, 339-345. "No automatic retry" is false unless `getClient` sets `retry: false`. Name how `rate_limited`, `not_found` and `retry-after` are detected, state the `pages.update` payloads, and reconcile the two signatures of `writeReservationState`. A missing `Acheté ?` returns 502 before the 422 check.

**A10. Undefined terms and sources.** (CO-1, CR-12, CO-4, CO-10, CO-14)
`concepts_brief.md`, "the owner", "reconciliation", "Public only" filter, `x` and `y`, and the data-source id are used without definition or link. Five places justify choices by process history a new reader cannot verify.

**A11. Required sections and rationale.** (CR-9, CR-10, CR-11)
There is no Risks & Mitigations section (the content is scattered). Alternatives A, J and M are rejected only on "the parents decided"; C and F lack the decisive trade-off. The Open Question at line 57 points to intro wording that is not in the plan.

**A12. Unresolved decisions in the plan.** (IR-6, IR-7, IR-9, IR-10, IR-11, IR-12)
Cancel error mapping, the cookie-change rule, response bodies, final French copy, the client rewrite details and automated test coverage for the Notion layer, routes, proxy and table.

### 🟢 Nit

*   **Simplicity.** Single `[action]` route instead of two files; delete the unused `checkbox.tsx` and `input.tsx`; remove the "Optional extras" question; revert to strict `x/y` parsing or fix the Goal wording; fold Alternatives G, H and I into Goals and Non-Goals. (ZO-6, ZO-8, Z8-7, Z8-8, Z8-9, CR-19)
*   **Structure.** Reorder Open Questions; split CUJ 4; add one error-path CUJ; fix the ambiguous state table and the packed response table; fix the "two new calls" list. (CR-13 to CR-16)
*   **Wording and terminology.** Unify `acheté`/`achete`/`Acheté ?` and `x/y` versus `acquise/totale`; remove filler and duplicated statements; fix French copy and apostrophes; pin `vitest`; split the dense reserve step 7 and `act` handler sentences. (CR-18, CR-20 to CR-24, IR-14 to IR-20)

## Traceability matrix

| Action item | Stage 5 | Stage 6 | Stage 7 | Stage 8 | Stage 9 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| A1 re-read | ZO-2 | CO-3, CO-6 | CR-1, CR-2, CR-3, CR-8 | Z8-1 | IR-6 |
| A2 cookie guarantees, stale record | ZO-5 | | CR-4, CR-5 | Z8-2, Z8-3 | |
| A3 identity and logging | | CO-7 | CR-6 | Z8-4 | IR-17 |
| A4 config checks, list route | ZO-4 | CO-12 | CR-17 | Z8-5 | IR-13 |
| A5 HMAC reuse | ZO-1 | | | | IR-8 |
| A6 build order claim | | CO-2 | | Z8-6 | IR-1 |
| A7 405 vs 404 | | CO-5 | CR-7 | Z8-7 | IR-2 |
| A8 async handler APIs | | | | | IR-3 |
| A9 SDK retry, error mapping | | | | | IR-4, IR-5 |
| A10 undefined terms | | CO-1, CO-4, CO-10, CO-14 | CR-12 | | |
| A11 risks section, rationale | | | CR-9, CR-10, CR-11 | | |
| A12 unresolved plan decisions | ZO-3 | CO-13 | | | IR-6 to IR-12 |
| Nits | ZO-6 to ZO-8 | CO-8, CO-9, CO-11, CO-15, CO-16 | CR-13 to CR-24 | Z8-7 to Z8-9 | IR-14 to IR-20 |

## Coverage and limits
- Stage 7 critics reviewed lines 1-280 only. Stage 9 reviewers audited lines 281-464 against the real code under `src/`.
- No stage reviewed any file outside the target document and the existing source files named above.
- Stage 8 ran on the unedited document, so its recommendations (drop the re-read, drop `already_reserved`, remove the proxy 503) are proposals for the author to decide, not settled findings.
- Reviewers cannot run the app. The claims about Next.js (404 versus 405) and the Notion SDK (retry defaults) come from the reviewers reading the code and type definitions in the repo and should be confirmed during the fix.

example-consolidated-report.md on GitHub

Do this Monday

Check claude --version. You need 2.1.271 or later.
Run the two install commands from egm-install.sh in a project, then open a new session.
Add EGM artifact directory: docs/egm to that project's CLAUDE.md.
Pick one feature you have not built yet where a mistake touches shared data, privacy, permissions or money. Run /egm:egm-brainstorm on it in one sentence.
Run /egm:egm-draft, approve the design section by section, then /egm:egm-review <design> and read the five reports.
Run /egm:egm-resolve. Answer the escalated issues yourself, and contest any fix that weakens your goal.
Open a fresh session and send: "Build the feature exactly to the approved design in docs/egm/.md; add tests." Then test the risky path yourself.
For your next small, clear fix, open skip-or-review.md and go straight to your normal workflow.

Go further

Other commands we left out. The plugin also has /egm:egm-bootstrap and /egm:egm-drift-report, a second workflow for an existing codebase and a weekly drift check. We did not run them, so we say nothing about how well they work.

Other harnesses and mixed models. We ran Claude Code only. The reviewers use model: inherit, so they ran on our session model and can share its blind spots. We did not try other harnesses or mixing models.

Plan Mode and other planners. We did not score EGM against Plan Mode or other planning tools. The pilot above is the only head-to-head we cite, and it is small.

Honest limits of our run.

The claim-ledger fix for the race came out of resolve after we contested the review, and it was never re-reviewed by any goldfish.
The fix relies on Notion keeping one order for simultaneous appends. Notion's documentation does not promise it.
The 30 of 30 result ran against a stand-in for Notion. The design's own race check against a copy of the real database was not run. Run it before you ship.
The review checks documents and code, and cannot run the app. Two framework claims in our report (404 versus 405, SDK retry defaults) come from reading code, and the report says to confirm them.
Rensin's 30% and the field report's figures are their authors' numbers, not ours.

FAQ

Do the reviewers see my CLAUDE.md or our chat? No. They exclude the conversation, and omitClaudeMd: true hides CLAUDE.md and the other instruction files. They still read the plan and any accessible file s2.

Why are my review files at the repo root? Claude Code has no artifact directory by default s23. Add the EGM artifact directory: line to CLAUDE.md.

Do I have to answer every issue in resolve? No. Answer the escalated ones, then reply "auto accept" to batch-apply the proposed fixes. Contested items are skipped s24.

Is a green test suite enough proof? No. Ours passed 216 tests, yet the race check against real Notion was still undone. Test the risky path yourself.

When should I skip the review? For a small, clear fix, as the README says s25. In our run, that fix cost $0.0455 and 10 s without it.