Design doc
Write and review the durable work order for a systemic or critical change before code exists. Use when asked for a design or architecture document for work that alters shared state, persistence, a public contract, cross-component architecture, security, or a fail-closed boundary, or when `development-loop` triages work as more than bounded. Send bounded fixes and small features to `development-loop`.From its SKILL.md
npx -y skills add dfrysinger/skills --skill design-docAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
10.7 KB, as published. Nobody here has run it
design-doc
A design document is a work order: it says what to build without the conversation that produced it. Someone who was not in the room — a future agent, a compacted context, you next month — can build from it.
That is the bar. A document that only makes sense to whoever wrote it has failed, however thorough it looks.
This skill owns the scope and architecture call. It ends when the document is
written and reviewed. It does not build anything; development-loop owns
forward motion.
1. Fix the scope
State the objective in one sentence, then write the non-goals.
Non-goals do more work than the objective. They are the boundary a later reviewer is held to, and the defence against a bounded fix growing into a speculative framework. Name the code, behavior, and callers explicitly outside this change, including generalizations you considered and rejected.
Ask what a supported caller needs today. A generalization required by a hypothetical future caller belongs in the non-goals, not the design.
Complete when the objective is one sentence and at least one non-goal names something a reasonable person would otherwise have assumed was in scope.
2. Classify: systemic or critical
Systemic — the change intentionally alters shared state or concurrency, persistence or version authority, a public API, schema, migration, or protocol, cross-component architecture, a reusable framework or central data-access boundary, or multiple independent user flows.
Critical — security, authentication, authorization, data loss or corruption, privacy or compliance, production infrastructure, audited controls, or fail-closed enforcement.
Critical wins when both apply. A critical document additionally carries an explicit rollback path and states what evidence proves the boundary fails closed.
Work that turns out to be bounded — localized, reusing established architecture,
touching none of the boundaries above — does not need this document. Say so and
send it to development-loop, even when the document was what you were asked
for.
Record the lane in the document. development-loop reads it back to size its
later gates, so a lane left unstated silently downgrades review, specialist
coverage, and the final end-to-end run.
Complete when the document names one lane; for critical, a rollback path and the evidence that proves the boundary fails closed.
3. Record constraint provenance and the reframe gate
Architecture is shaped by constraints, so record the ones that materially narrow the design before selecting mechanisms. For each hard constraint, write:
- the constraint;
- its provenance: user outcome, policy, platform behavior, measured capacity, compatibility promise, or implementation default;
- the evidence or owner that makes it binding;
- the outcome or invariant it protects;
- the condition that requires it to be revisited.
Every hard numeric limit needs measured demand, platform evidence, or a named policy owner. Prior configuration and earlier implementation are provenance, not proof that the limit must remain.
Define the design's reframe gate. Implementation returns here before adding another component when a recorded revisit condition fires, a new subsystem mainly preserves an implementation default, repeated fixes merely move failure to the next internal boundary, or a proven predecessor now satisfies the supported caller with less machinery.
The reframe record answers:
- What user-visible outcome is blocked?
- Which constraint creates the blocker, and where did it come from?
- What concrete invariant fails if the constraint changes?
- What is the simplest design without that constraint?
- Which option has fewer trusted components and maintenance surfaces?
The answer replaces further implementation until the work order and its review reflect the new architecture.
Keep one durable reframe status in the work order:
CLEARmeans no recorded revisit condition is currently met; state the evidence used to reach that conclusion.OPENmeans implementation is stopped; record the triggering evidence and answer all five reframe questions above.
Implementation starts or resumes only from CLEAR. Closing an OPEN record
requires the revised work order and its design review evidence, not merely an
author statement that the concern is resolved.
Complete when every architecture-shaping constraint has provenance and a
revisit condition, every hard numeric limit has external or measured
justification, the document names the conditions that force reframing, and its
durable reframe status is CLEAR with evidence or OPEN with all five answers.
4. Write the document
Write or update a durable document containing:
- objective and non-goals;
- the lane from section 2;
- the constraint-provenance record and reframe gate from section 3;
- reuse contract — what existing helper, state owner, API, or error pattern carries this, and why anything new is required rather than convenient;
- affected data flow and the existing connection points it touches;
- realistic failure model — how this breaks in production, not in theory;
- hard invariants and acceptance criteria;
- migration and rollback when relevant;
- deterministic check definitions (section 5);
- a short Definition of Done under its own heading, covering exactly this change's scope.
Put it where the work lives — the repository, alongside the code it governs — so a future agent inherits it. A design that exists only in a chat transcript is not durable.
Give the Definition of Done a unique heading. Downstream runs point at it by name.
Complete when every element above is present and the acceptance criteria are observable — each one names something that can be checked, not a quality someone would have to judge.
5. Define the check contract
For each proposed test or guard, state:
- the behavior or invariant it protects;
- the setup, input, or state transition that exercises it;
- the expected pass and failure signal;
- why that failure proves the intended contract.
Prefer, in order:
- types and schemas that make invalid states impossible;
- behavioral tests;
- dependency and architecture checks;
- text matching, as a temporary ratchet only.
Reach for guardrails only for cross-cutting rules likely to drift that types
and functional tests express badly. An invariant that is useful but not needed
to ship this change is tagged REGISTER-ONLY in the invariant register, or
recorded as follow-up work, rather than blocking.
Name any guard that must exist before implementation to constrain the work, and
why. development-loop writes it; nothing executable is created here.
Everything else is written alongside the implementation and reviewed with it.
Complete when every acceptance criterion in section 4 has at least one check that would fail if the criterion were violated.
6. Review the work order
Run dual-review's normal bounded loop over the complete design document and
its check contract. Tell both reviewers this is a design review so
dual-review applies its disclosed architecture and scope lens before
implementation detail.
Start with dual-review's standard packet. For this review, both reviewers also
receive:
- this
design-docskill as the authoring and completion rubric; - the
scoutreport, when one informed the chosen direction; - the issue, user decisions, architecture documents, ADRs, invariants, or repository conventions that directly constrain the design;
- the constraint-provenance record, including every inherited default that materially shaped the design.
The design document is the subject under review; the other artifacts are evidence and rubric. Keep unrelated discovery, rejected alternatives, and historical discussion out of the packet.
Complete when dual-review's verification criteria are met.
7. Stop
The work order is finished. Present it.
Continue into implementation only on an instruction that already exists —
given in advance ("write the doc, then continue to development-loop") or after
you present it. On that instruction, hand the document to development-loop,
which owns whether the run is attended and every gate from build through land.
Complete when the reviewed document is presented, and development-loop is
invoked if an instruction to continue already exists.
Pitfalls
- Transcript as design. A document that assumes the reader saw the conversation is not a work order. Write for the agent who arrives after a compaction.
- Non-goals left empty. The section that constrains reviewers and prevents scope growth is the one most often skipped, because it is the only one that costs something to write.
- Designing for hypothetical callers. Generalization justified by a caller that does not exist is the most common way a systemic change becomes a critical one.
- Inherited mechanism as requirement. A prior limit, service, or protocol is evidence about history, not proof that the new design must preserve it.
- Literal charter compliance. A work order can remain internally consistent after its assumptions stop serving the user outcome. That is when its reframe gate should fire.
- Unobservable acceptance criteria. "Handles errors gracefully" cannot pass or fail. Each criterion names a checkable state.
- Check contract as a test list. Naming tests without stating what each proves produces coverage that passes while the invariant is broken.
- Building. Writing code here skips every gate
development-loopowns — live proof, implementation review, landing — because none of them have run yet.
Verification
The document is done when:
- the objective is one sentence and the non-goals are explicit;
- it names one lane, with rollback and fail-closed evidence when critical;
- every architecture-shaping constraint has provenance and a revisit condition;
- the durable reframe status is checkable, and implementation proceeds only
while it is
CLEAR; - the reuse contract explains why anything new exists;
- acceptance criteria are observable;
- every acceptance criterion has a check that would fail if violated;
- it carries a Definition of Done under a unique heading;
- the bounded
dual-reviewprocess met its verification criteria; - someone who was not in the conversation could build from it.