Final Shape Review

final-shape-review.md

name

final-shape-review

description

Re-examine a nearly merge-ready implementation after review comments are addressed to ask whether the final data shapes, contracts, types, transitions, interfaces, ownership boundaries, and abstractions can be materially simplified before merge. Use when the code works and feedback is resolved, but the implementation may still carry discovery scars from trial and error and you want a bounded late-stage zoom-out pass that pushes the merged shape toward obvious, boring, future-maintainable code.

Final Shape Review

Use this skill after the change is functionally correct and the active round of review comments is addressed, but before final handoff or merge. Use it to zoom out once the hard part is over and ask: now that the real solution is visible, what would this code look like if it had felt obvious from the start?

Explicit invocation of $final-shape-review grants permission to launch the required parallel subagents described below. Explicit invocation of a higher-level review skill that names $final-shape-review as a required step also grants permission for this skill's required subagents.

What good looks like

• Leave merged code that feels much simpler than the path it took to discover it.
• Leave future developers with a shape they can read cold, trust quickly, and modify without fear.
• Prefer code that feels boring, inevitable, and easy to extend over code that advertises how hard it was to build.
• Make the next change cheaper by removing path-dependent abstractions, extra hops, and complexity that only exists because the implementation was found incrementally.

Goals

• Reconstruct the intended end state from the issue, plan, and boundary contracts rather than from the implementation journey.
• Separate necessary structure from discovery scars, temporary scaffolding, and path-dependent abstractions.
• Question the implementation across data shapes, contracts, types, transitions, interfaces, ownership boundaries, and helper layers.
• Leave either a materially simpler merge-ready diff or a crisp deferred simplification note. No change is a valid outcome.

Review standard

Prefer changes that delete concepts, flatten indirection, remove duplicate shapes, preserve source-of-truth types, or move logic to the owning boundary. Reject changes that mainly rename, rewrap, or redistribute complexity.

Do not let the effort it took to discover the solution justify keeping complexity in the merged code. Trial and error is part of implementation. It is not entitled to survive in the final shape.

Land a simplification now only when all of the following are true:

• the better shape is clear now that the work exists
• the change is bounded and re-verifiable
• the simplification materially improves clarity or correctness
• the risk of reopening the PR is lower than the cost of carrying the extra complexity

Required review vectors

Launch exactly 3 parallel subagents with the same context bundle and different simplification lenses:

1. Data shapes and contracts
   • duplicate schemas or parallel types
   • unnecessary transforms or adapter objects
   • widened primitives, stringified IDs, or source-of-truth drift
   • request or response shapes that could collapse into one clearer contract
2. Transitions and control flow
   • extra states, branches, flags, and normalization hops
   • orchestration layers that only shuffle data
   • retry, error, or loading flows that can be expressed more directly
   • transitions that belong closer to the owner boundary
3. Interfaces and ownership
   • wrappers, factories, helper matrices, and pass-through modules with low payoff
   • logic living in the wrong app, package, or layer
   • APIs that expose the implementation journey rather than the final concept
   • places where deletion, inlining, or boundary moves would simplify the system

Required context bundle

Before delegating, gather and pass the concrete files the reviewers need:

• repo root AGENTS.md
• nested AGENTS.md files for the changed areas
• docs/PLANS.md
• docs/design-docs/index.md
• docs/design-docs/core-beliefs.md
• any design doc directly relevant to the seam
• the relevant issue, workpad, PR body, or active ExecPlan when one exists
• a short summary of the review comments just addressed, when that context matters
• the changed files plus nearby callers, validators, types, tests, and proof surfaces

For Next.js work in this repo, read the installed Next docs first, not memory.

Delegation protocol

1. Read the context bundle yourself before spawning subagents.
2. Spawn the 3 required subagents immediately.
   • Give all 3 the same context bundle.
   • Assign each one review vector.
   • If you explicitly choose model settings, use the smartest model available and the highest reasoning effort available.
3. Tell each subagent to:
   • assume the current behavior is already correct
   • re-derive the cleanest honest final shape from the requirements and repo rules
   • compare the current implementation against that cleaner shape
   • identify discovery scars, path-dependent abstractions, and complexity that future developers would have to mentally pay for
   • prefer deletion, flattening, merging, or boundary correction over new abstractions
   • prefer code that a future developer can read cold and safely modify
   • return only material simplifications, not style nits
4. While they run, do your own zoom-out pass locally.
   • Reconstruct the intended end state from the issue, plan, or PR.
   • Inspect the changed files and the nearby boundaries they forced into scope.
   • Sketch 2-3 plausible simpler shapes in your head, then discard the ones that only move complexity around.
5. Wait for all 3 reports.
6. Synthesize the overlap, not the loudest single opinion.
7. Apply the worthwhile simplifications that are clearly in scope.
8. Rerun the narrowest affected validation immediately.
9. Update the workpad or PR-facing summary so it describes the final post-review shape and any deferred simplifications.

Required subagent output

Require every subagent to return these sections:

1. Current shape worth keeping
2. Discovery scars still visible in the implementation
3. Material simplifications worth doing now
4. Material simplifications better deferred
5. Best alternative final shape
6. Risks of changing now
7. Feedback to ignore

Push them toward second-order simplifications. The target is not "rename this helper." The target is "why does this helper, wrapper, or extra shape exist at all now that the implementation is known?"

Main-agent synthesis

Present the combined take with these headings:

• What to keep
• Discovery scars still visible
• Simplifications worth doing now
• Simplifications to defer
• Feedback to ignore
• Recommended final shape
• Plan of attack

Prefer overlap across reviewers. If all 3 circle the same simplification, treat that as strong evidence. If they diverge, choose the direction that best matches repo ownership rules, canonical types, and the smallest honest end state.

What to change automatically

If you are in an unattended implementation flow, apply only the simplifications that are clearly worth the churn now. Prioritize:

• deleting dead wrappers, dead helpers, or dead intermediate shapes
• collapsing duplicate types or contracts back to the source of truth
• removing one-off adapter layers or pass-through modules
• flattening control flow that became simpler once the feature was complete
• moving logic to the owning package or boundary when the move is local and clarifying

What to defer

Defer the simplification instead of landing it now when it would:

• reopen settled product behavior or acceptance criteria
• change public or cross-package contracts across a wide caller set
• require migration handling or a broad retest surface
• turn the end of the PR into a new architecture project
• be subjectively cleaner but not clearly better

When deferring, leave one crisp follow-up note in the existing workpad or tech-debt system that states the better target shape and why it was not worth landing in the current PR.

Stop rules

• Do not treat every late-stage pass as permission to redesign the feature.
• Do not churn stable code outside the changed area just because a new pattern seems nicer.
• Do not add a new abstraction in the name of simplification unless it clearly deletes more complexity than it creates.
• Do not reopen reviewer-approved behavior without a strong correctness or clarity reason.
• Do not force a refactor when the honest answer is that the current shape is already good enough.
• Do not preserve complexity just because it was painful to discover.
• Do not let this devolve into style cleanup. The point is structural simplification.