packet

name

packet

description

Author a gate/sprint review packet from a committed blueprint: gather the gate's bead evidence and receipts, populate the reader's-own-checklist status grid with a divergence strip, a capped FAQ, and exactly three linked receipts, carry the decision vocabulary into the reader's repo, then verify it headlessly and share the single packet.md markdown file. Use when the user says "build the packet", "gate packet", "sprint packet", "assemble the G2/G3 packet", or when a gate/sprint reaches close and needs a review artifact for a cold reader.

Packet

Encapsulate gate/sprint packet authoring. The blueprint — proven on the Gate 1 packet and its cold-read council — lives as a committed template instead of an agent's memory, so every packet has the same reader-first shape: the reader's own checklist answered at a glance, deviations surfaced immediately, evidence linked not dumped, and a verifier that catches the failure modes (broken anchors, an overgrown FAQ, missing receipts) before the reader ever sees them.

When to Use This Skill

Run at a gate or sprint close that needs a review artifact for someone who was not in the work — a reviewer, a stakeholder, a cold agent. Skip it for internal checkpoints with no external reader.

Companion: packet-deepdive validates a drafted packet with parallel cold-read lanes. Author with this skill; validate with that one.

Core Process

Phase 1 — Gather evidence

From the gate and its beads:

1. The reader's checklist — the exact wording of what the reader asked for (their plan text, the gate's deliverable list). The status grid uses their words, verbatim — not your restatement.
2. Gate bead evidence — bd show the gate epic and children, close reasons, commit/PR links. Each grid row's verdict must trace to a bead outcome.
3. Receipts — the three proofs: a double-run/determinism capture, the test-gate output, and the PR/merge trail. Store the raw outputs in a receipts/ dir; the packet links them.
4. Divergences — where the delivered work differs from the reader's plan text, and whether each was pre-registered (a deliberate day-one narrowing) or found in review. This is the highest-trust content: surface it, don't bury it.

Phase 2 — Carry the decision vocabulary in

The reader can see the target repo, not the planning workspace where the decision record (D*/A* tags, amendment log) normally lives. Any tag the packet references must be explained in the packet or the target repo. This is a hard constraint, not a nicety — a packet that cites D4-L1 the reader can't resolve is a dead reference. The overlay names where the vocabulary import lives; if absent, inline the definitions.

Phase 3 — Draft against the template

Copy template.md and fill it. The blueprint constraints it encodes:

• Status grid — one row per reader-checklist item, in their words, with the verdict bold in the cell and linked evidence.
• Divergence strip — a blockquote in the same eye-span as the grid, so deviations hit before the reader scrolls. If there are none, say so in one line rather than omitting the strip.
• FAQ — hard-capped at 5. Admission rule: a named reader voice actually asked it (or would, cold). Do not pad to 5.
• Prose ≤ 700 words (tables, code, and the agent on-ramp don't count) — a target, warned not enforced.
• Receipts — exactly 3, linked, not dumped inline.
• Optional agent on-ramp — a paste-in orientation prompt so a cold agent reads the packet, not the aspirational design docs.

Write the packet to the consuming repo at docs/<gate>/packet.md (per the packet naming convention).

Phase 4 — Verify

python3 <skill-dir>/render.py --in docs/<gate>/packet.md --verify

The share artifact is the markdown file itself — a single, simple packet.md (reader preference, 2026-07-16: plain markdown over generated HTML). render.py --verify runs checks-only with no output file; the HTML render (--out) remains available as an optional offline view but is no longer the share step. The verifier runs headlessly (no browser):

• Blueprint checks — grid present, FAQ ≤ 5 (error if over), exactly 3 receipts (error otherwise), divergence strip present (warn), prose ≤ 700 (warn).
• Anchor integrity — every intra-page #link resolves to a heading id; a dangling cross-link is an error. This is the failure mode a browser would hide and a cold reader would hit.

Fix every error before sharing. Warnings are judgment calls (the G1 packet ran to ~1100 prose words and shipped — a documented, deliberate exception).

The renderer deliberately does not run a browser. Gate packets are prose + tables + links; if a packet needs rendered diagrams (mermaid), that is the architecture-packet builder's headless-Chromium path, out of scope here.

Phase 5 — Record

• Commit packet.md and receipts/ to the target repo (plus the rendered HTML only if the optional render was produced).
• The share the reader receives is the single packet.md markdown file.
• When this skill first lands, update the gate-packet-blueprint memory (if the project uses one) to point at the committed template — the template is now the single source of truth, not the memory.

Project Overlay

Reads .agents/overlay.md § packet in the consuming repo (shared overlay convention — one file, one section per skill):

Key	Meaning	Default when absent
reader_checklist	Where the reader's own deliverable wording lives	Ask / infer from the gate bead
decision_vocabulary	Path to the decision-record tags to carry into the packet	Inline definitions as needed
packets_dir	Where packets are written	docs/<gate>/
receipt_commands	Commands whose output becomes the receipts	Project's standard test/run

With no overlay: infer the checklist from the gate bead, inline any decision tags, write to docs/<gate>/.

Anti-Patterns

• Restating the reader's checklist in your words. The grid must use their wording verbatim, or they can't map it to what they asked for.
• Burying divergences. Deviations go in the strip, in the grid's eye-span — not in a section the reader reaches after deciding you're done.
• Padding the FAQ to 5. The cap is a ceiling, not a quota. Every entry earns its place by being a question a reader actually asks.
• Dumping receipts inline. Three linked proofs, not three walls of console output. Link the stored capture.
• Dead decision references. Citing a D*/A* tag the reader can't resolve in their repo. Carry the vocabulary in.
• Shipping on a red verifier. A dangling anchor or an over-cap FAQ is an error for a reason — the cold reader hits exactly those.
• Hand-writing the HTML. If the optional HTML view is rendered, it is generated from packet.md; never hand-edit it (overwritten on every render). The share is packet.md itself.