Skip to content

Altitude-First Staged Review: Simplicity Check Before Detail, Again After Fixes

Altitude-first staged review checks a design for simplicity, YAGNI, and reuse before detail reviewers run, then repeats that check after their fixes land.

Altitude-first staged review orders the reviewer passes on a design document from high level to low. A simplicity reviewer runs first and asks whether the design needs to exist in this form. Comprehension and critic reviewers follow. The simplicity reviewer then runs again on what their fixes added, and the detailed plan review comes last. The worked example is the Elephant-Goldfish design review plugin at commit 36343a1. Its zoom_out reviewer runs at stages 5 and 8 of five stages numbered 5 to 9 (egm-review).

Stage Reviewers What it checks
5 Zoom Out zoom_out Problem framing, speculative features, reuse
6 Comprehension comprehension Whether a fresh reader can follow the document
7 Critic design_critic, structural, style Single points of failure, scaling limits, edge cases
8 Intermediate Zoom Out zoom_out Additions and mitigations since stage 5
9 Implementation readiness implementation_readiness, codebase_details, style The detailed plan against the codebase

The focus column follows the stage breakdown in the upstream review design doc.

Why simplicity comes before detail

The design doc states the reason. The zoom-out pass checks framing, rejects speculative features, and verifies reuse "before investing in detailed review passes" (review.md). Detail reviewers can spend a full pass on a feature that a later scope review would cut (inference).

The zoom-out standard also fails the review at once when the reviewer cannot tell what the design is for and why (zoom-out standard). The altitude rules then bound the later stages. The skill keeps a code-level rubric out of comprehension review, because "it asks for code-level detail, which the Zoom Out standard forbids in FeatureRange" (egm-review).

Why the check runs again after fixes

Stage 8 audits "additions, modifications, and defensive mitigations introduced during Comprehension and Critic reviews". It purges "speculative complexity and YAGNI elements" before task planning (review.md). Each mitigation the author adds in reply to the stage 7 critic is new surface for the second pass to judge (inference).

The second pass is incremental. The skill gives the stage 8 reviewer the path of the stage 5 report and tells it to focus on additions and mitigations (egm-review). The design doc adds that the pass avoids "re-flagging decisions accepted in Step 5" (review.md).

Sequential stages, parallel reviewers

The Claude guide keeps stages 5 to 9 sequential and allows parallel reviewers only inside the current stage. Each stage's report and required remediation complete before the next dispatch. "Uninterrupted mode skips human checkpoints, not these stage dependencies" (Claude integration).

The skill also bans multi-select menus. Combinatorial checklists are "strictly prohibited to protect topological dependencies" between the five stages (egm-review). One preset skips both zoom-out passes anyway, because the implementation-plan-only review jumps straight to stage 9 (egm-review).

Prompt text sets this order, and a run can break it. The Claude Code 2.1.308 harness run on 2026-10-22 records an "Initial stage-order failure". A focused nine-reviewer rerun then verified sequential stages (TESTING.md). The TESTING.md row does not say how the order broke.

A reviewer that reads only the document cannot tell whether a proposed helper already exists (inference). The zoom-out persona must "perform code searches in the codebase to verify whether equivalent or similar components already exist" for proposed new components (zoom_out persona). The Claude adapter gives it Read, Grep, and Glob (adapter).

Trade-offs

  • Launch count. The zoom-out reviewer accounts for 2 of the 9 reviewer launches in a full pass (egm-review).
  • Wall-clock time. Each stage waits for its slowest reviewer (inference from the Claude integration).
  • Anchoring. Upstream passes the stage 5 report to avoid repeat findings. The report also shows the second reviewer the first one's view (inference). Upstream does not discuss that effect.
  • Source drift. The stage 5 reason comes from a design doc, and issue #271 reports that the design docs drift from the shipped skills. The skill text confirms the stage 8 focus, not the stage 5 reason.
  • No outcome data. Upstream reports no measurement of whether this order gives better designs. Its FAQ says "Completing the EGM workflow alone does not demonstrate a productivity improvement" (FAQ).

Key Takeaways

  • Give the second simplicity pass the first pass's report and the changes since then, so it judges new text and leaves accepted decisions alone.
  • Grant the simplicity reviewer read and search tools over the codebase; a document-only reviewer cannot judge reuse.
  • Check stage order in the run record, because a prompt-set order broke once on Claude Code.
  • Treat a preset that skips the scope stages as a separate review mode with no simplicity check.
  • Do not cite EGM as evidence that altitude-first ordering improves designs.
Emerging — single recent source Last reviewed: 2026-11-03