Synthesize Spec

Synthesize Spec

Produce a ratified, decomposable spec from a brief — the upstream half of a large build. Both reference builds' upstream halves were multi-day, multi-context efforts with operator decision rounds; a single-context "write me a spec" call cannot hold that. So this skill has the same shape as the build itself: a durable research ledger whose rows are executed in fresh contexts, exactly as orchestrate-build executes tickets, then synthesis, adversarial review, and operator ratification.

The mental model. State lives on disk (docs/research-ledger.md). Cognition lives in fresh contexts (each research/design row; the review pass). Sequencing is a loop that reads the ledger, runs the next unit, writes the ledger back — so drive-build.sh --skill synthesize-spec can drive it, honoring pauseRequested and stopping at operator-decision points. It hands off to decompose-spec by writing docs/decomposition-prompt.md.

The layout it reads and writes (docs/research-ledger.md, docs/research/, docs/design/, the spec, docs/decomposition-prompt.md) is defined in skills/build-memory/layout.md; this skill cites it and does not restate the tree.

Orient (every invocation)

Resolve the mode from the ledger, the way orchestrate-build orients:

• No docs/research-ledger.md yet → plan (§ modes/plan.md).
• Ledger present → read its CURRENT STATE block (nextUnit, projectStatus, round). projectStatus: DONE or spec Status canonical → nothing to do; report and stop. An open research/design row is nextUnit → run. All rows done, no spec yet (or a new round) → synthesize. Spec written, not yet reviewed → review. Reviewed and dispositioned, awaiting operator → ratify.
• An explicit mode input overrides.
• pauseRequested: true or an unanswered operator-decision (⚑) row that blocks progress → report and stop (this is the human's decision surface, like a gate).

Then follow the matching mode file below; each ends by updating the ledger's CURRENT STATE + change log and returning here.

The modes

Why fresh contexts and a ledger (not one big prompt)

• Research is broad and lossy. A single context that reads dozens of sources to write a spec has forgotten the early sources by the end. Each row's fresh context reads exactly its sources and writes a durable note; the spec is synthesized from the notes, not from a decayed context.
• Review must be independent. A context that just wrote the spec is a biased reviewer of it (the same self-preference bias implement-spec and decompose-spec guard against). review runs in a fresh context given the spec + the ledger, not the authoring history.
• Operator decisions are first-class. The §Q register and ⚑ markers make the human's rulings part of the durable record, and ratify is the one place they are required — no spec goes canonical with open questions.

What this skill does NOT do

• No decomposition, no implementation — it produces the spec and the decomposition-prompt.md hand-off; decompose-spec and implement-spec take it from there.
• No inventing findings — nothing is cited that was not read (the ledger's standing rule); an inaccessible source is recorded as INACCESSIBLE, never paraphrased into a claim.
• No ratifying on the model's own say-so — canonical requires the operator's answers to the open Q rows.