Review Packet

Review Packet

Overview

Package the current work into one self-contained, routed document that something outside this thread can use: an external reviewer, the adversarial-review critic, or a brand-new agent thread continuing the work. One file — a routing preamble, a shared context core, and a continuation layer.

Core principle: a reader can only use what they can see. A reviewer can't critique reasoning that isn't written down; a fresh thread can't resume work whose status, file locations, and next step aren't written down. The packet carries both the reasoning and the state.

When to Use

• Hand a design to an external reviewer (paste into ChatGPT/Codex/Gemini).
• Feed adversarial-review — its context core (§2–§7) becomes that skill's requirements.md; it injects its own plan-critic.
• Catch up / hand off the work to a new thread or a different agent (you're out of context; someone else continues).
• Not for: reviewing a code diff (use /code-review).

Workflow

1. Locate the design. Newest docs/superpowers/specs/*-design.md; if there's no spec, reconstruct from this conversation.
2. Mine the conversation for what the next reader cannot see — both the reasoning and the state:
   • original request, verbatim; background + invariants; the decision log (chosen, why, and what was considered + rejected/deferred, and why); the soft spots (proactive);
   • current status — what's done / in-flight / pending / blocked; current rev; last decision;
   • artifact & file map — absolute paths to the spec, this packet, the skill/code, the branch;
   • next actions & how to resume — the immediate next step, what to read first, which skill/command to run, and the working conventions to honor (e.g. never commit; the brainstorm→writing-skills/writing-plans flow; project rules).
3. Fill every REQUIRED slot in references/packet-template.md (including §0 routing and §9–§11).
4. Write to docs/superpowers/specs/YYYY-MM-DD-<topic>-review-packet.md. Do not commit.
5. Hand off. Print the path and which sections each consumer reads (review / adversarial-review / catch-up). Offer to print inline.

What Makes the Packet Work (the contract)

• Self-contained — inline everything; it works even for a reader with no repo access.
• Routed — the §0 preamble sends each of the three consumers to its sections, so the review wrapper never hijacks a catch-up or adversarial-review reader.
• Expose the reasoning — rejected/deferred alternatives with their why.
• Surface soft spots honestly — a dedicated "scrutinize these" section.
• Continuation-complete — a fresh thread can resume from it alone: current status, an absolute file map, and the immediate next action are all present and concrete.
• Adversarial (for the review consumer) — the wrapper tells an external reviewer to find problems; for adversarial-review, feed §2–§7 and let it inject its own critic.

Common Mistakes (from baseline testing)

Reference

• references/packet-template.md — the section skeleton with REQUIRED slots. Fill all of them.