Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / component-review-planning

Component review planning

Component review planning turns a measured visual specification into a review packet that can be checked before page code is written. It maps the approved comp to assets and code decisions, records the exact source state under review, and gives the review workspace enough context to collect a trusted plan decision.

Planning boundary

The planning stage sits between region specification and first-viewport review. It answers whether each painted region has the right asset and whether each code-planned region is a suitable choice for page code; the assembled first-viewport review later judges how those choices work together. See Component fidelity review workflow for the wider fidelity gates and comparison process.

flowchart LR
    A[Measured spec and approved comp] --> B[Build review plan]
    B --> C[Check plates and capture proof]
    C --> D[Inspect plan in workspace]
    D --> E{Decision}
    E -->|Approved| F[Allow page work]
    E -->|Changes requested| G[Update regions or assets]
    G --> B
    F --> H[First-viewport review]

The plan is an explicit checkpoint for a comp-led build. If the spec has no raster region and no code region that needs a decision, the stage is skipped because there is no plan to review. (crates/context/src/component_review/plan.rs#L17-L30, crates/context/src/component_review/plan.rs#L140-L148)

Review items

The plan divides the visible comp into two review classes. An asset item represents a raster region such as a plate, image, or texture. A plan item represents a code region that needs a human decision because its visual treatment may not be safe to reproduce as ordinary page code.

The packet also lists code regions that need no plan decision. These regions remain visible on the map so the reviewer can check coverage and can later reclassify one as an asset if the comp shows that code is not enough.

Packet entryReview purposeReviewer view
Asset itemCheck whether the produced plate, image, or texture matches its mapped comp region.Generated asset beside the comp crop
Plan itemCheck whether the region should stay drawn in code and whether its mapped area is correct.Comp crop with the planned code description
Code regionShow covered content that does not need a plan decision yet.Mapped region on the comp

References: crates/…/plan.rs• L11-30 crates/…/plan.rs• L100-135 ui/…/plan-model.ts• L5-18

Region mapping

Each review entry keeps the region id, name, kind, note, and normalized box from the measured spec. The box ties the decision to a visible part of the approved comp, so the reviewer can inspect both the local material and its place in the whole composition.

The planner keeps a code region as a plan item when it has a visual warning, is marked as code-drawn artwork, or is non-container chrome with more than a flat surface or straight rules. This rule keeps painted marks and ornaments in the decision queue while leaving simple grounds, bands, and rules as map context. The planner checks and clamps boxes to the comp frame rather than allowing a review item to point outside it.

References: crates/…/plan.rs• L14-25 crates/…/plan.rs• L37-45 docs/PLAN-REVIEW.md• L80-105

Plate availability

Every raster region must have a usable plate before the plan opens. The planner resolves the plate to a project-relative path, checks that the file exists, and reports all missing raster regions together. This makes the plan a complete asset checkpoint instead of a partial list that could hide missing material.

The approved comp remains the reference. A plate is the production asset to review, not a direct comp crop. A missing plate stops plan creation and sends the workflow back to asset production; a present plate is then captured and pinned as part of the review evidence. Component fidelity review workflow describes the later plate quality and placement gates.

References: crates/…/plan.rs• L82-99 crates/…/plan.rs• L110-139 tests/…/component-review-plan-missing-plates.json• L1-7

Plan packet

The plan packet is the durable description of one plan round. It uses schema version 3 and the components stage so the same review session can receive new rounds while preserving the identity of the component-review journey.

Packet identity

The packet records the approved comp path and dimensions, the measured spec digest, the ordered review components, and the remaining code regions. Asset previews point to plate files. Plan previews point back to comp crops because no code output exists yet. Component names are derived from stable region ids, which keeps labels readable without changing the source identity.

Flagged items are placed first, followed by other assets and then ordinary plan items. This order puts the highest-risk material in front of the reviewer while keeping the order stable inside each group. (crates/context/src/component_review/plan.rs#L117-L148, ui/component-review/plan-model.ts#L37-L57)

References: crates/…/plan.rs• L82-148 ui/…/plan-model.ts• L15-20 ui/…/plan-model.ts• L47-57

Plan persistence

The project command writes the packet to .impeccable/…/components.json by default. The review session then stores a frozen copy outside the builder project, with source hashes, captured files, the current draft, receipts, and prior revisions. The project packet is the input to preparation; the outside session is the record used by the review service and later checks.

Each changed round gets a new packet revision and revision-scoped preview URLs. Older rounds remain readable, so a later capture cannot silently replace the pixels that a reviewer saw. Atomic file replacement and one writer lock keep readers from seeing partial state or competing submissions.

References: crates/…/plan.rs• L7-10 crates/…/plan.rs• L151-157 crates/…/store.rs• L12-54 crates/…/store.rs• L202-283

Decision carry-over

When a new round is prepared in the same build journey, an approval carries forward only when the component revision is unchanged. A changed region, changed plate bytes, changed spec digest, or changed source identity creates a new decision target. This lets the reviewer focus on repair work without allowing an old approval to cover new material.

Feedback creates a new round rather than changing a submitted record. The round history shows what changed, what was added, and which approvals remain valid. A replaced plate or changed spec makes the prior accepted plan stale and requires a new review round.

References: crates/…/store.rs• L231-280 crates/…/plan.rs• L199-230 ui/…/plan-model.ts• L244-270

Plan lifecycle

The plan lifecycle separates packet creation, evidence capture, human decision, and downstream permission. A plan receipt records the decision for one exact packet revision; it does not claim that later page code or the assembled first viewport is correct.

StateMeaningNext action
Awaiting reviewThe packet and proof exist, but no decision receipt is stored.Serve the session and wait for the reviewer.
ApprovedEvery item is accepted, no missing region is marked, and inventory is confirmed.Allow the build to proceed to page work and later first-viewport review.
Changes requestedThe reviewer asked for asset changes, region-map changes, reclassification, splitting, or added missing regions.Apply the receipt and prepare a new round.
StaleThe pinned spec or source files no longer match the reviewed state.Prepare a new round; do not reuse the old receipt.
ClosedAn assembled first viewport was accepted for the current review journey.Continue later build work without requesting component or assembly review again for that journey.

Submission decisions

An asset can be approved, revised with feedback, or requested as separate layers when one generated image combines material that should move independently. A plan item can stay in code or receive feedback that changes its region map. A plan item can also be reclassified as a plate, image, or texture. A code region that was not a plan item can be reclassified from the coverage map.

Approval is stronger than approving the listed rows. It also confirms that the reviewer found no uncovered part of the comp. Any revision, reclassification, or missing mark changes the receipt to changes-requested, so the agent must apply the notes before it can present the next round.

References: ui/…/plan-model.ts• L20-27 ui/…/plan-model.ts• L111-159 crates/…/store.rs• L352-438

Build gate

The build gate checks for an accepted plan in the current build journey before page code work can continue. It accepts the plan only when the packet has a matching current spec digest and its pinned sources still match. A later accepted first-viewport review is terminal for the journey and supersedes the earlier plan checkpoint; it does not broaden the scope of what that first-viewport approval means.

References: crates/…/plan.rs• L160-230 crates/…/lifecycle.rs• L7-35 docs/PLAN-REVIEW.md• L5-9

Plan-aware workspace

The review workspace detects a schema-version-3 components packet and opens a plan-specific flow instead of the assembled-page review. It presents an introduction, one mapped item at a time, and a final coverage summary. The workspace keeps the approved comp as the common reference while changing the comparison view to match the item's role.

Item inspection

For an asset item, the workspace shows the generated file beside the matching comp crop. The reviewer can inspect transparency against the comp colour or a neutral background, compare the prior round when one exists, and use a magnified view for detail. For a plan item, the workspace shows the comp crop and states what will be drawn in code; it does not pretend that a page preview exists before page code is written.

The comp map remains available from each item. It shows the item box and all other mapped regions, which helps the reviewer judge whether a plate should extend under a code region or whether a region should split into separate material. (ui/component-review/plan-review.ts#L266-L354, ui/component-review/plan-review.ts#L420-L479)

References: ui/…/plan-review.ts• L283-354 ui/…/plan-review.ts• L420-479 ui/…/entry.ts• L40-57

Coverage inspection

The summary map exposes code regions that were not decision items and lets the reviewer mark a visible comp area that the packet did not cover. A marked area needs a name and a valid box before submission. The same map can request that an uncovered code region become an image, which sends that reclassification separately from decisions on listed items.

This coverage step prevents a clean list of decisions from being mistaken for a complete map. The reviewer can therefore approve the plan only after checking both the listed entries and the unlisted visible regions.

References: ui/…/plan-review.ts• L357-418 ui/…/plan-review.ts• L547-575 ui/…/plan-model.ts• L91-108

Review navigation

The workspace places flagged items first and moves through pending items until it reaches the summary. The progress row, map, item cards, prior-round notes, and read-only submitted view all describe the same draft. This keeps a reviewer’s decision attached to the current component revision instead of to a screen position.

When a round is stale, the workspace disables submission and explains that a new round is needed. When a receipt exists, the round becomes read-only. The service serves the packet and pinned files only for the local review session, and it stays pending if no browser reviewer is available.

References: ui/…/plan-review.ts• L52-88 ui/…/plan-review.ts• L381-444 crates/…/server.rs• L54-83 crates/…/mod.rs• L121-164

Validation boundary

Validation protects the link between the plan decision and the exact evidence that produced it. It checks the packet identity and revision, each component revision, the current source hashes, the completeness of missing-region data, and the inventory confirmation required for approval.

The capture proof for this stage is plan-specific. It covers every packet component, records the comp crop or raster-source evidence, and is checked for intact blobs and matching sources before a receipt can satisfy the lifecycle gate. A receipt export by itself is not authority; the stored session state and its pinned evidence are the authority.

References: crates/…/store.rs• L337-438 crates/…/plan.rs• L184-230 docs/PLAN-REVIEW.md• L65-71

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the spec region kinds, surface readings, normalized boxes, and planner selection rules aligned. A region moved between components and codeRegions changes what the reviewer must decide.
  • Keep plate paths, plate hashes, packet previews, and plan capture proof aligned. A valid asset on disk must remain the same asset the reviewer sees.
  • Keep packet revision, component revision, spec digest, and carried approval rules aligned. A changed plate or region must not inherit an old approval.
  • Keep the plan submission contract aligned between the workspace and the store. Approval depends on every decision, valid missing boxes, and inventory confirmation.
  • Keep the components stage distinct from the hero stage. Plan approval permits the next build step but does not approve the assembled first viewport.

Important failure modes

TriggerConsequenceGuard
A raster region has no plateThe plan is not written, so review cannot start with incomplete assets.Plan creation lists every missing plate and stops.
A spec or plate changes after approvalThe old receipt no longer authorizes the current work.The gate checks the spec digest and pinned source hashes before reuse.
A visible comp region is absent from the packetThe reviewer could approve an incomplete plan.The workspace supports map coverage checks, missing marks, and inventory confirmation.
A plan item is revised without describing the map changeThe agent cannot know how the region boundary or material should change.Plan-item revisions require reviewer feedback.
A decision targets an old packet or component revisionFeedback could be applied to the wrong evidence.Submission requires matching request, packet, and component revisions.
The review service has no available browser reviewerThe build must not treat silence as approval.Headless service runs leave the review pending.
A submitted round is edited againThe saved receipt would no longer describe one stable decision.Submitted rounds are read-only and new work uses a new round.

Key files

FileWhy to read it
crates/…/plan.rsDefines how the measured spec becomes the plan packet, checks plate availability, and gates page work.
crates/…/store.rsDefines frozen session state, revisions, source checks, submission validation, and persistence.
crates/…/lifecycle.rsDefines accepted, stale, and terminal review states across the build journey.
ui/…/plan-model.tsDefines plan item roles, decision rules, summaries, and submission readiness.
ui/…/plan-review.tsDefines the plan-aware inspection flow, coverage map, missing marks, and reviewer actions.
ui/…/entry.tsRoutes schema-version-3 packets into the plan workspace and reports stale or failed sessions.
crates/…/server.rsServes packet revisions and pinned files and accepts the single decision submission.
docs/PLAN-REVIEW.mdRecords the plan stage contract and its place before first-viewport review.
docs/native-capture-and-component-review.mdGives the parent overview of native capture, durable review sessions, and downstream approval.
docs/component-fidelity-workflow.mdExplains the related spec, plate, comparison, and fidelity-gate workflow.