pixtuoid: Command for GitHub Copilot

Implementation-plan brief — the review, shifted left

The upstream twin of pr-review.prompt.md: the review protocol catches the repo's known failure classes after the code exists; this brief front-loads the same classes while each costs one plan line instead of a finding plus a fix round. Census grounding: at least 4 of the 7 post-merge escapes and the one design-class miss (PR #86's parallel config structure) were plan-preventable.

When to use: new feature, new config key / CLI flag, new seam or module, any change touching a documented sharp edge, or any change you expect to span ≥3 source files. Skip for (overrides the file count): typo/docs fixes, mechanical renames/moves, single-file bugfixes with an obvious pinning test — right-size the process; don't 700-line-plan a 300-line change.

The plan must answer (the mined failure classes, moved left)

Every section gets an answer; "n/a" counts only with a reason.

1. Design gate cleared (arc-loop step 3) — before the sections below, the plan states the approach passed the gate: the idiomatic way is confirmed against real docs/source (not memory); the design survived an adversarial pass; the deepening lens ran (deletion test — does this deepen a module or add another shallow one = AI-slop?). Name any big-radius refactor the deepening warrants — a slop-reducing refactor is in-scope here, not deferred by default.
2. Data shapes — for every NEW field, config key, map, or collection: name its identity/key-space. If it overlaps an existing structure's identity (two collections keyed by the same id; an attribute map shadowing an entity list), the plan consolidates into one entity type or justifies why not. Shared IDENTITY consolidates; shared TOPIC stays separate (the [pet-names] lesson). A JOIN of two existing collections names its join key and verifies it against the real production constants IN THE PLAN — the plan that ASSUMED registry id == install-target name shipped a CRITICAL caught only at review (R0613-16).
3. Consumers — every new field, parameter, or asset names the consumer this same change wires up. A plan line "add X" without "Y reads X at Z" is the unwired-addition smell (CONTRIBUTING pitfall 5) at its cheapest fix point — _snap_prev shipped unconsumed and defeated its own PR.
4. Siblings — every guard, fix, or NEW SURFACE enumerates its sibling paths up front (Unix/Windows arms, twin call sites, parallel manifests — for a config key: the docs and manifest twins) and says which get the same treatment in this change (pitfall 2's in-diff form). 3b. Reachability — a guard protects an OUTCOME, so enumerate every path that reaches that outcome, not just the one the bug arrived through, and give each a disposition (guarded here / already guarded at X / genuinely exempt because Y). Mechanical, not from memory: rg the function the outcome flows through and read EVERY call site. This is distinct from item 3 — siblings are parallel IMPLEMENTATIONS (a per-source decoder, a platform arm), reachability is the call sites into ONE implementation, and a plan can enumerate the first while missing the second entirely. The ghost-gate arc is the worked example: the first-sight gate was written, reviewed and live-verified against !known files while emit_first_sight had a SECOND caller on the append path — rg emit_first_sight returns both in seconds — so the shipped fix did nothing for the ordering a running pixtuoid actually meets. State the ORDERINGS too where the outcome is timing-dependent (boot-then-write vs write-then-boot): they are reachability in the time axis and the verification plan must exercise each.
5. Untrusted input — if the change touches transcript/hook/file/config input, name the decode boundary where it is sanitized (pitfall 3), and whether any user-visible truncation is char-safe (pitfall 1). A denylist's enumeration cites the platform's DOCUMENTED set, never memory (pitfall 6).
6. Tests — name the failing test each implementation step starts with (the repo is TDD-first), then the refusal paths those tests will pin — BOTH sides of every window/threshold, with offsets derived from the constant under test (pitfall 4).
7. Sharp edges — read the doc comment on every declaration this design touches and list the constraints they state (tests/, Raycast and site keep theirs in the guide). They are the documented hazards exactly where you are about to work: what looks like a bug and is deliberate.
8. Verification plan — the gates to run, and any watch-it requirement: motion/pose changes render an animation and WATCH it; sprite changes run the beautify-decoration loop. Verification steps are blocking plan items, not checkboxes — PR #61 shipped five walk regressions behind an unchecked "live run" checkbox. Name the CI-ONLY gates the change can red (semver, api-surface, doc-check, gen-check, wasm-check, windows-test, snapshots): just preflight is blind to all of them, so "preflight green" is a claim about a SUBSET and must say so — the ghost-gate arc reported all-green with api-surface and doc-check both red. And reproduce the REPORTED scenario, including its ordering (item 3b), not a convenient one: a repro built from the artifact left on disk re-runs the state you already fixed and proves nothing about how it got there.
9. Layering / orchestration boundary — if the change adds or crosses a layer seam (a mechanism/foundation layer with an orchestrator over it, like install ← sources), name the ONE orchestration entry point and design the lower layer's mechanism API as pub(crate), never pub: callers reach it ONLY through the orchestrator, never directly. Do NOT expose an underlayer/foundation API as crate-public so something can call it around the facade — that is a design leak unreachable_pub can't catch once the module itself is reachable, so the plan is where the single-gateway shape is decided (install/uninstall route SOLELY through crate::sources; the plan states "no second caller" and which existing direct calls collapse into the orchestrator). A new public seam on a lower layer needs a one-line justification of why the orchestrator can't own it.