End-State Review
Reconstruct the target as if the settled requirements had been known from the
start. Remove history-shaped complexity from the proposal without erasing real
contracts, migrations, or rollout obligations.
Default to review-only. After explicit approval, update planning artifacts
only. Do not modify implementation in this workflow; leave code changes to a
separate implementation request.
Resolve the Review Target
- Review the user-named plan, roadmap item, specification, change, diff, or
migration. When no artifact is named, infer the smallest plausible target
from the current discussion and repository planning state. Ask when
materially different targets remain plausible.
- Read the target completely. Inspect governing requirements, direct user
decisions, relevant implementation, callers, tests, history, and external
contracts only far enough to test the proposed final shape.
- Keep direct user intent, planning claims, implementation evidence, and
external obligations distinct. A proposal does not prove an obligation, and
absence from the plan does not prove that a deployed contract is dead.
- Bound the review to complexity introduced, retained, or locked in by the
target. Mention unrelated debt only when it invalidates the proposal; do not
absorb it into the review.
State the End-State Contract
Describe in a few sentences what should be true when the work is finished:
- the user-visible outcome;
- the domain rules and ownership boundaries that must survive;
- the public, persisted-data, migration, security, or rollout obligations that
constrain the design;
- material non-goals.
Ask only when a missing answer could materially change that contract. Do not
choose a cleaner architecture by silently changing product behavior.
Separate Residue from Obligations
Inspect modes, flags, wrappers, aliases, fallbacks, duplicated policy, parallel
flows, temporary schema, transitional names, and workaround plan steps. For
each consequential candidate, record its evidence and classify it as:
- Remove — no current consumer, contract, or migration need remains.
- Consolidate — the behavior is real but its rules or ownership are
duplicated.
- Retain temporarily — a current rollout or migration requires it; name the
exit condition.
- Retain permanently — a domain or external contract justifies the cost.
- Unresolved — evidence or a user decision is still required.
Search real callers before recommending deletion, but do not treat an empty
repository search as proof when use may be dynamic, reflective, configured,
persisted, or external. Require stronger evidence in proportion to the cost of
being wrong.
Reconstruct the Coherent Shape
Design from the end-state contract rather than replaying the sequence of
earlier decisions.
- Prefer one clear product path over mode flags or parallel implementations.
- Give each shared rule, such as permissions, routing, URL state, feature
gating, or command naming, one evident owner.
- Integrate with an existing sound boundary before adding a side channel,
adapter, or new abstraction.
- Split a surface only when state, lifecycle, layout, control, or domain
ownership creates a durable boundary.
- Prefer product-intent names over names that preserve implementation history.
- Do not invent a framework for one current use or preserve machinery for an
imagined future.
- Keep staged rollout and backward compatibility when evidence shows they are
live obligations.
- Keep the proposed rework no broader than necessary to make the target
coherent.
Reconcile the Target
For a planning target, identify obsolete steps and propose the smallest set of
replacements needed to express the coherent end state. Preserve approved
scope, non-goals, acceptance conditions, and sequencing that reflects real
dependencies rather than historical discussion order.
For an implementation target, describe the desired code shape, likely
deletions, and affected consumers. Stop at recommendations even when a fix
looks safe. Code mutation requires a separate request.
Map each end-state outcome and retained obligation to validation. Include
tests for deleted assumptions when navigation, permissions, persistence,
external consumers, or rollout behavior could regress.
Apply the Planning Gate
Keep the repository unchanged during the initial review. Treat an explicit
instruction such as
or
as approval
to edit only the reviewed planning artifacts. Acknowledgement, continued
discussion, or agreement with the analysis is not edit approval.
When applying an approved planning revision:
- Replace superseded proposal text instead of appending a conversation log.
- Record the end-state outcome, retained obligations and exit conditions,
material non-goals, validation, and the next implementation action. Link to
an existing contract source instead of duplicating requirements that it
owns.
- Preserve the planning system's ownership and queue invariants.
- Re-read the touched files and verify that no old step contradicts the
approved final shape.
- Stop without starting implementation or changing code.
Report
Return only sections that carry information:
- End state — the reconstructed final contract.
- Residue and obligations — candidates, evidence, and disposition.
- Proposed shape — the coherent design and material tradeoffs.
- Plan amendments — replacements needed or approved edits made.
- Verification — behavior and deleted assumptions to prove.
- Decisions required — unresolved load-bearing choices.
- Scope boundary — relevant work deliberately left outside the review.
A defensible conclusion that the target is already coherent is valid. Do not
manufacture debt or claim that any review can guarantee zero technical debt.