R017 · AI-built software and its verification › Agent delivery workflows

Elephant-Goldfish Model: deep-context drafting, zero-context review

Read the original

agent-workflowssdlcdesign-reviewcontext-isolationdocs-as-codehuman-oversight

TL;DR

The Elephant-Goldfish Model (EGM) separates the agent that drafts a spec from the agents that review it. The drafter (Elephant) carries the whole conversation; each reviewer (Goldfish) is a fresh subagent that sees only the spec and the files it links. Anything the spec relies on but never says is invisible to a Goldfish, so it gets flagged. Google open-sourced it as a plugin for Claude Code, Codex and Antigravity (Apache 2.0, "not an officially supported Google product").

The core idea is sound and cheap to adopt: it is self-containment testing for design docs, plus context isolation as a defense against confirmation bias. The plugin is heavier than the idea. It is a nine-persona, five-stage pipeline with strict prompt-level rules, and several of its guarantees (phase write boundaries, reviewer isolation from AGENTS.md / GEMINI.md) are conventions or partly verified, not enforced.

Sources

The idea, from Rensin's essay

Rensin's claim is "design is the new code": when an AI writes the code, the micro-decisions a human used to leave in the logic must move left into the design doc, or nobody responsible for the system will understand it. He reports the method grew out of an internal tool that reached more than 100,000 Googlers within months, with dozens of contributors.

Three observations drive it:

  1. Re-bootstrap from a doc. After a crashed session, a written statement of intent and progress restores context in seconds; re-feeding code does not.

  2. Models sprint off cliffs. Given context but no guardrails, the agent invents APIs and architecture. The doc's file-by-file plan is the guardrail.

  3. sizeof(docs) << sizeof(code). Docs are a cheaper, more reliable context source than source code.

The workflow:

  1. Grow the Elephant (no code). Load context, have the model summarize it back, then hold a 20–30 minute design argument under a "no code" rule. Push back on sycophancy ("you are not being helpful"; "why do you think that?"). Have the model propose the first design itself, because that tests whether it understood. Debates can run hours or days.

  2. Teach the Elephant. Write the doc section by section: Problem, Technical Plan, Alternatives (rejected ideas as guardrails against later hallucination), Detailed Implementation listing every file to create or change and why.

  3. Goldfish protocol. Fresh sessions run a comprehension test ("explain what this does and how my system works"), a critic review (he finds about 30% of suggestions valuable, an anecdote), and an implementation-readiness test. Loop until findings are nitpicks, then human review.

  4. Implement with guardrails, then a deliberately harsh AI code review.

For legacy code he proposes "peanuts and hay": generate README.md files bottom-up from leaf directories, with a human fixing each leaf (he says the AI is about 50% wrong there), then roll summaries upward to the root. He says this takes about a week regardless of codebase size. READMEs can retire once design docs cover every file. The essay closes with the claim that engineers are becoming managers of agents.

How the plugin implements it

The plugin turns the essay into seven skills, nine stateless reviewer personas (agents/) and versioned rubrics (resources/document_standards/). Install is one command per harness; Claude Code uses claude plugin marketplace add google/elephant-goldfish-model then claude plugin install egm@egm.

Skills. egm-brainstorm interviews you, then sends the idea to a seven-lens Goldfish swarm (Contrarian/YAGNI, cost and token economics, developer ergonomics, migration and backward compatibility, observability/SRE, long-term tech debt, and an "Inventive Catalyst" that hunts for the trade-off being accepted as inevitable) and writes concepts_brief.md. egm-draft writes design_draft.md section by section with a checkpoint after each. egm-review runs the pipeline below. egm-resolve brings findings back into the Elephant's context, classifies each as PROPOSE FIX or CONTEST, and applies approved edits. egm-review-loop runs any reviewer set against any document. egm-bootstrap is the peanuts-and-hay README generator. egm-drift-report compares checked-in docs to current code and reports only differences (missing features, missing fields, hardcoded shortcuts, architectural divergence).

Semantic split. The reviewer finds a ## Detailed Implementation Plan heading (or a synonym) and splits the doc into a FeatureRange above it and a DetailedRange below. Design critics see only the architecture; readiness reviewers see only the plan.

The five-stage review (numbered 5–9 in the skill):

StageReviewers (fresh subagents)ReadsRubricReport
5 Zoom outzoom-out, inventive-catalystwhole doc + linked fileszoom-out standard (simplicity, YAGNI, reuse)zoom_out_report.md
6 Comprehensioncomprehension (spawned directly, no synthesizer)the doc alonenone: paraphrase test for self-containmentcomprehension_report.md
7 Criticdesign, structural, styleFeatureRange + linked filesfeature-spec standard (scale, failure modes)critic_report.md
8 Zoom out againzoom-outwhole doczoom-out standard, aimed at what stages 6–7 addedintermediate_zoom_out_report.md
9 Implementation readinessimplementation-readiness, codebase-details, styleDetailedRange + linked filesimplementation-readiness standard (paths, signatures, tests)implementation_readiness_report.md

A synthesizer persona fans reviewers out in parallel, dedupes and writes the report; where a harness cannot nest subagents, the orchestrator dispatches reviewers directly. Presets run all stages interactively, all at once into a consolidated_review_report.md with Blocker / Major / Nit priorities and a traceability matrix, feature-spec only (5–8), or readiness only (9). Each stage allows at most one re-audit, after which remaining findings are recorded as accepted trade-offs.

Design choices worth noting.

Tradeoffs and failure modes

The weakest point is that "zero-context" removes the conversation but not the model. A Goldfish running the same model as the Elephant shares its priors, so the errors it misses are correlated with the drafter's. Context isolation fixes conversational confirmation bias; it does not add an independent perspective.

Review checklist

Use this when adopting EGM, or when judging any "fresh reviewer" design-review setup.

Filed as R017 under 3.3 Agent delivery workflows, also 4.1, 6.1 and 7.2.

Connections

See R017 on the knowledge map

Part of the Research notes on nowucca.com. Figures and claims are the source's own unless the summary says otherwise.