v1.0.0 to v1.1.0

---

name: synthesis-decision-packet

description: Collect many parallel decisions from a principal in one sitting instead of one per turn. Generates a self-contained HTML packet — one row per decision carrying the item, the agent's recommendation, the reasoning, and a link — with buttons, a per-row note box, local persistence, and a paste-able summary the principal returns in a single message. Use when you owe five or more decisions of the same shape; when a review, migration, upgrade, triage, or backlog pass has produced a list someone must rule on; or when a per-item conversation is burning round-trips.

license: "Apache-2.0"

depends_on: []

metadata:

author: "Rajiv Pant"

source_repo: "github.com/synthesisengineering/synthesis-skills"

source_type: "public"

---

# Decision Packet

An agent that has analysed N items needs N decisions from its principal. Every default shape

fails at scale, and the measurement that produced this skill is blunt: **26 rounds of per-item

conversation produced 0 of 30 decisions. One packet produced 30 of 30, in one pass, in one

paste.**

| Shape | Why it fails |

|---|---|

| One question per turn | N round-trips. This is what cost 26 rounds. |

| One long prose report | The principal holds thirty judgments in their head, keeps their place, and composes a reply that re-identifies each item. |

| A table in chat | Readable, not operable. Nowhere to record a decision, no state if they stop halfway. |

| A form that submits somewhere | Needs a backend, and the reply still has to get back to the agent. |

The failure is not that the principal lacks information. **The medium collects no structure**, so

the burden of structuring the response falls on the person, every time, for every item.

**The property to preserve above all others: the principal's cost scales with the number of

*sittings*, not the number of *items*.**

## When to use it

Load when you owe your principal **five or more parallel decisions of the same shape**, each

needing supporting context, where you have a defensible recommendation per item and the decisions

matter enough to deserve attention but are too numerous for per-item conversation.

Natural fits: review findings to fix or waive · dependency bumps to take or hold · drafts to

publish, edit, or kill · files to migrate or leave · flaky tests to quarantine or fix · features

to build now, later, or never · candidates to advance on a defined rubric.

## When NOT to use it

- **Fewer than about five decisions.** Just ask in chat. The generator refuses below five without

`--allow-small`.

- **The decisions are not parallel in shape.** A packet of unlike questions is a form, and a form

is worse than a conversation.

- **You have no recommendation per item.** Then the packet is a questionnaire and *your analysis

is not finished*. Do the analysis. The generator refuses a packet where no row carries a

recommendation.

The failure mode of a good pattern is over-application. These three limits are the skill.

## The five load-bearing properties

Requirements, not suggestions. Each is why it worked.

1. **Self-contained rows.** Item, recommendation, reasoning, and a link to the underlying

artifact. The principal never leaves the packet to decide.

2. **The recommendation is marked on the control, not merely stated in prose.** Agreeing costs one

click. The agent's judgment does work instead of being described.

**It is deliberately not pre-*selected*** — a packet that opens fully decided cannot distinguish

"I agreed" from "I never looked", and would report decisions nobody made.

3. **A free-text box on every row, beside the buttons.** Never force a principal into your option

set. In the origin run one such note, on one row, carried information no button could have.

4. **Local persistence keyed per item.** Thirty decisions is more than one sitting for anyone doing

it properly. Storage access is guarded: where a browser blocks it the packet still works and

says so in the summary.

5. **A paste-able summary the tool generates.** *This is the property that closes the loop.* The

structure you need is produced by the packet, not composed by the person.

## Content requirements, which matter as much as the mechanics

- **Name filters from the content, not from generic severity.** "Needs a fix", "We disagreed",

"Ready as written", "Not yet decided" — so the principal picks their own path through the set

rather than going 1 to N.

- **Surface disagreement; never converge before the principal sees it.** Eight rows in the origin

run showed two reviewers' conflicting verdicts and the principal broke all eight ties.

Converging first would have shown a false consensus. Use the `disagreement` block.

- **A summary band before the detail**, so the shape of the work reads in three seconds.

- **Severity in form as well as words** — the coloured rail per row is how the eye finds exceptions

while scrolling.

- **Recommend against your own prior work where that is true**, including failed hypotheses. A

packet that only argues one way is a sales document, and the buttons stop being trusted.

## Use

```bash

python3 scripts/build_packet.py --schema # the spec format

python3 scripts/build_packet.py spec.json --stdout # to a pipe

```

Write a JSON spec, generate, hand over the file. It is self-contained: no build step, no

dependencies, no server. It opens from disk, over a local HTTP server, or published as an

artifact, in light or dark, on a phone or a laptop.

**Generate from a data array; never hand-author rows.** Thirty hand-written blocks drift. One

array with a render loop cannot. That is the whole reason this is a generator rather than a

template.

The generator validates before it emits and refuses to build a broken packet: duplicate ids

(they key persistence), a recommendation outside its own option set, a packet with no

recommendations at all, malformed disagreement blocks.

## Two defects that are permanent fixtures

Both shipped in the reference implementation; one reached the principal in real use. They are

regression-tested in `scripts/test_build_packet.py`.

- **Charset in the first bytes.** Without `<meta charset="utf-8">` ahead of everything, typographic

punctuation renders as mojibake when served over a plain local HTTP server. *Found by loading

the page, not by reading the source* — which is why the fixture asserts on bytes and why you

should always open a generated packet before handing it over.

- **The copy control must never fail silently.** `navigator.clipboard.writeText` is blocked inside

a sandboxed artifact iframe with no `clipboard-write` permission; in the origin run the button

did nothing and *said* nothing, and the principal worked around it by hand. The required order:

**select the textarea first** so a manual ⌘C/Ctrl+C always works, say something *synchronously*,

then `document.execCommand("copy")` (which does work in sandboxed iframes), then the async API,

and report honestly which path succeeded. A third fixture was added on 2026-08-28 after driving

the real button surfaced an empty status line while the async promise was unsettled — an

unbounded silent interval is the same defect as a permanent one.

## Relationship to other skills

- **`synthesis-autopilot`** should *call* this, not reimplement it. Autopilot requires "batched

questions for the user"; this is the concrete artifact that requirement was missing. A

round-trip budget only means something if one round-trip can carry many decisions.

- **The adversarial review family** — this is where an engagement surfaces its unresolved

disagreements. Pair it with a status for findings that are not open, not conceded, and not the

agents' to close.

- **Handoff queues** move work *between agents*. The decision packet moves decisions *between

agent and principal*. Together they are the two directions that stop routing everything through

a person as the transport layer.

## Related

- `references/worked-example.md` — a complete spec and what it produces.

- `synthesis-thinking-framework` — for deciding *what* to recommend before you build the packet.

- `synthesis-anti-shortcuts` — a packet whose rows hedge instead of recommending is the

asking-as-shortcut costume in a new medium.