Repository navigation
Description
Problem Statement
Several Spec Kit commands judge work rather than create it: /speckit.analyze, /speckit.converge, /speckit.clarify, /speckit.checklist, and in the bundled extensions /speckit.bug.test and /speckit.assess.decide. Today they run in the same agent session that wrote the spec, plan, tasks, code or fix being judged.
That session is the worst possible reviewer of its own work. It knows what was meant, so it reads what was meant instead of what is on the page. It fills gaps from memory that a reader of the files would hit; it believes the tasks it just finished are done; the agent that wrote a bug fix verifies that fix; and the session that championed an idea through assessment gives the go / kill verdict. The output looks rigorous, but it is steered by everything in the context window.
Google's Elephant-Goldfish Model (google/elephant-goldfish-model, the original essay) names the fix: the elephant (the session holding the context) drafts and decides, and goldfish (fresh subagents that see only the documents and the code, never the conversation) review.
Proposed Solution
An opt-in preset, fresh-eyes, that wraps the six judging commands with strategy: wrap. It changes no core template, and it survives upgrades because it composes on top of them. I have it working locally on Spec Kit 1.4.0.
The protocol (one shared file, PROTOCOL.md):
- Prepare, do not judge. The elephant does only the command's setup: arguments, path safety, the prerequisite script, extension hooks before and after, overwrite questions, and any user questions. It may read the artifacts to do that, but it forms no view on their quality. If the agent cannot start subagents, the command stops; it never falls back to judging its own work.
- Brief each goldfish with facts only: the command's own instructions and which steps are theirs, the resolved paths, the user's arguments verbatim, a lens, and the return format. A brief never holds a summary of the conversation, what was intended, what to look for, or earlier findings. If a sentence would steer the reviewer, it is left out.
- Spawn three goldfish in parallel. They change no project file, and anything needing the user's consent comes back as
needs-consent: <command>instead of being run. - Merge, check, report. Duplicates are merged, and a finding two goldfish reached independently is marked stronger. The elephant may drop a CRITICAL or HIGH finding only if it can disprove it against the source, and it says so. It never overturns a failed check or a judge's verdict. The command's own report format is kept.
- Writes wait for the user. The elephant edits spec.md, tasks.md, checklists and reports only for the findings the user approves.
The panel per command:
| Command | Fresh agents | Elephant keeps |
|---|---|---|
| analyze | 3 lenses: consistency and coverage · constitution and governed facts · ambiguity and "could a stranger build this from these files alone?" | report, ids, remediation offer |
| converge | 3 lenses: requirements and success criteria vs code · every task (ticked or not) vs code, plus code beyond the intent · plan decisions, constitution MUSTs and tests | appends only the approved tasks; "none approved" is never reported as converged |
| clarify | 3 lenses split the ambiguity taxonomy; one more goldfish validates the updated spec at the end | asks the user the questions and writes the answers |
| checklist | 3 lenses over the quality dimensions | asks the scoping questions first, then merges, numbers and checks the item rules |
| bug.test | 3 lenses: reproduce · regressions · try to break the fix | judges verified / partial / failed; the fixer never verifies the fix |
| assess.decide | 3 independent judges (no lenses) | merges cautiously: lowest rating per criterion, and any kill vote caps a go at needs-clarification |
Lenses are used where coverage matters (finding things), and independent judges where independence matters (a single verdict).
Evidence
The strongest evidence came from building the preset. I wrote it, then ran one fresh reviewer, with no view of my session, over the preset and the six generated commands. It returned 20 findings I had missed (6 high), all real. Among them:
- a goldfish told to read the full command file meets the "you are the elephant" instructions and can recurse;
- nobody owned the extension hooks;
- assess.decide could merge three scorecards into a
gothat breaks its own rule ("evidence must be adequate or better"); - converge's lenses never covered success criteria, constitution MUSTs or unrequested code.
I had reviewed my own work and was satisfied, so the missed findings are the problem this proposal addresses, in miniature. After the fixes, a second fresh reviewer found no high-severity problems, and 23 medium or low gaps in who owns what, which I also fixed. The loop converged the way the model predicts. I have not yet run the preset end to end on a real feature; that is the next step in my own project.
Alternatives Considered
- Editing the generated command files (for example adding
context: forkin Claude Code's skill frontmatter). This is simpler, but it is wiped by everyspecifyupgrade, it is agent-specific, and a forked command cannot ask the user anything, which clarify and checklist need. - The EGM extension and preset already submitted ([Extension]: Add Elephant-Goldfish Model extension #5394, [Preset]: Add egm-opencode-subagents (Elephant-Goldfish Model OpenCode preset) #5395). They are complementary rather than overlapping: they port EGM's own design workflow (brainstorm, draft, review) into Spec Kit as
speckit.egm.*commands. This proposal applies the same rule to the judging commands Spec Kit already has, so the standard specify, plan, tasks and implement flow gets fresh eyes without adopting a second workflow. - One fresh reviewer instead of three. This is cheaper, and it is a reasonable setting. A single reviewer still shares one blind spot, and lenses measurably widen coverage.
Agent-agnostic notes
The protocol needs only one capability: starting a subagent with a fresh context and a written brief. My version names Claude Code's Agent tool and a model choice for the panel. A core version would phrase that per integration, or let the user configure it (panel size, model, on/off per command), and degrade by stopping with a clear message where an agent has no subagents.
Acceptance Criteria
- With the preset installed, each of the six commands starts fresh-context subagents for its judging steps, and the main session performs no judging of its own.
- No brief contains conversation context; briefs are paths, verbatim arguments, a lens and the return format.
- Every user-facing write still waits for the user's approval, and each command's existing report format is unchanged.
- Hooks, overwrite prompts and user questions remain with the main session.
- Removing the preset restores the stock commands exactly.
Offer
I'm happy to contribute this as a community preset through the [Preset] submission flow, or as a PR adding it next to constitution-sync as an opt-in core preset, whichever the maintainers prefer. I can share the full preset files here first.
AI Disclosure
I designed and reviewed this with an AI coding agent (Claude Code), which also drafted the preset files and this issue. I chose the commands, the panel shape and the merge rules, and I have read and stand behind the text.
Activity
infinitelyloopy-bt commentedon Nov 15, 2026
For context, here is where fresh eyes sits in the stock pipeline. Creation stays in the main session; only judging moves to fresh agents.
mnriem commentedon Nov 16, 2026
Note that you can already do a fresh command execution inside of your coding agent. Nothing prevents you from doing fresh eyes with that. Having said that making a preset that makes that process easier is something that you can do for sure. So I would love to see an externally hosted preset for sure!