Shells review focuses on structural wiring, not broad codebase patterns. Skip sweeping project-context reads — but spot-check any concrete codebase element a shell names (function, file, type, API surface) to verify it exists and can carry the contract the shell assigns to it. A shell whose Produces or Consumes cites a nonexistent or misdescribed seam is a structural wiring bug.
- Spec coverage — The union of every shell's
Covers Spec Requirementsfield must equal the full set ofR<N>IDs in the spec's## Requirementssection. Flag any R-id not covered by any shell. Partial coverage must be markedR<N> (partial: <what's deferred>)with the deferred work named in that shell's Open Questions. - Wiring — Every entry in a shell's
Consumesfield must trace to a prior shell'sProducesentry (check dependency ordering viadepends_onfrontmatter) or an explicit "from existing codebase" annotation. Flag missing prerequisites (Consumes with no source), dead ends (Produces not consumed by any later shell and not part of the final system's entry points), and implicit dependencies (Consumes tracing to a shell not independs_on). - Cited-element accuracy — For each external resource a shell names (file path, function, type, API surface, codebase reference, documentation link), open the cited target and verify it exists and supports the contract the shell assigns to it. Wrong citations pass spec-text review and surface later as unimplementable shells.
- Completeness — Walk through shells in dependency order, accumulating Produces. After the final shell, verify every spec requirement is satisfied by a reachable component. No component should be orphaned.
- No duplication — A bare
R<N>claiming full coverage must appear in exactly one shell. A partial markerR<N> (partial: <what's deferred>)may co-occur with other partial markers for the same R-id only when the deferred slices are non-overlapping. Flag: a bareR<N>appearing in more than one shell; overlapping partial slices for the same R-id; a bareR<N>co-occurring with any partial marker for the same R-id.
Flag an issue only when it would cause implementation problems, incorrect wiring, or spec coverage gaps. The issue must be discrete and actionable.
- P0 — Spec requirement missing from all shells, or shell chain produces a broken system
- P1 — Dead end, missing prerequisite, or implicit dependency that will cause implementation problems
- P2 — Moderate issue: duplicated requirement, unclear shell boundary, or ordering improvement
- P3 — Minor improvement
- Stylistic preferences that don't affect wiring or coverage
- Implementation details that belong in the expanded plan, not the shell