Design Doc

Converge a chosen concept into a design document for a module or system that a colleague who knows the field can review, and keep it true as results arrive. The finished document states what is proposed, which interfaces are fixed and which implementations are swappable adapters behind them, how each part is verified (a real run on fixed input, a contract test for the few contracts that warrant one, or evaluation), what evidence each decision rests on and what would reverse it, and which bets still wait for a measurement.

The skill works for any system design and is shaped for modules whose core behavior comes from a trained model, a judge, or an agent loop. There, whether the design can work is settled by measurement more than by specification, so the document carries its unmeasured bets and its reversal conditions openly instead of presenting a finished answer.

Ownership

This skill owns the document's semantic structure wherever the document is published, whether as Markdown in a repository, a Notion page, or another host: which sections exist, what each must contain, and how they change together. copydesk owns the prose in every section. write-notion owns Notion publication: it maps these sections onto its page layout and handles toggles, mentions, figure uploads, and checking the stored page. For a design doc bound for Notion, this skill supplies the sections and their content and write-notion places them, for example the Verification split in its test-plan section and the Threat model or Operating boundary in its security section. A host's layout changes where sections appear, not which sections exist.

A product requirements spec, user stories, or a ticket breakdown is a different genre, and a delivery deadline does not change that: the document carries the outcome, deliverable form, target date, and scope by that date as context and constraints, not as requirements or stories. Implementation tasks and schedule belong to a plan written with work-plan and linked from the document; the experiment queue here holds only the measurements that decide design questions.

Before Drafting

Confirm that a concept is chosen. A design document converges; it does not open the space. If the user is still asking what could be built, say so and offer design-exploration; if they hold one hunch they want attacked before committing, offer idea-critique. A chosen concept with unresolved parts is enough to start, because the unresolved parts become open questions and queued experiments.

Gather before asking. Read what earlier work left: exploration notes or a mechanism map, a critique, an Interview Brief, a bet scoped with praxis-direction, a delivery brief, measurements with their conditions, and literature notes. Carry each into its place: the exploration's root frames Context and Goals, and its rejected concepts with the user's stated reasons seed Alternatives; a critique's status and open attacks join the decision entry it tests, and its deciding measurement becomes a queue item; a bet's kill condition becomes a reversal condition; and an Interview Brief's confirmed decisions enter the decision log with their evidence kind. For brownfield work, read the code and existing interfaces and cite them at a revision; when the context lives in team records such as a tracker, chat, or wiki, reconstruct it with internal-source-research when installed and cite records the reader can open. Ask the user only for judgment the material does not settle, such as which goal wins a conflict or how firm a constraint is.

For product delivery with a deadline, carry the upstream bet or brief into the document: its outcome and deliverable form into Context and Goals, the target date into the header's Target line and into the decision log as a constraint entry with the role that can move it, and the scope promised by that date into Goals, with what will not fit by then stated as a Non-goal or as later work in the plan, each with its reason. The design still states mechanism, interfaces, verification, and open bets; a bet that threatens the date becomes an open question or a queue item, not a silent cut.