| name | design-doc |
| description | Org-Bench Google-bipartite winning mechanism — the 4-section design-doc gate that every non-trivial change passes through. Use when the Director defines new work, when an Integrator reviews a lane (code/quality/devops), when the Director approves, or when a Worker is about to start coding and needs the spec. Tools live in the `design-doc` MCP server. Triggers on phrases like "design doc", "design review", "approve revision", "lane verdict", "what does this issue require", "is this approved yet". |
design-doc — the gate
UltraThink projects do not start coding until a design-doc for the issue passes a 3-lane review (code, quality, devops) and the Director seals it. This skill loads when you are about to create, review, approve, or consume a design-doc.
The 4-section format (mandatory)
Every design-doc has exactly these four sections. They go into the sections arg of doc_create:
- what — The positive scope. "Add a
/api/billing/refund endpoint that calls Stripe refunds.create and writes a refund_events row."
- whatNot — Out-of-scope guardrails. "Does NOT touch the existing
charges flow. Does NOT add UI. Does NOT modify webhook handler."
- riskGuardrails — Known risks + the levers that contain them. "Risk: double-refund. Guardrail: idempotency key on (charge_id, requestId), 24h TTL. Rollback: feature flag
billing.refund.v1, kill-switch via Statsig."
- verificationSteps — Concrete, runnable checks. "1)
pnpm test billing/refund. 2) psql -c 'SELECT count(*) FROM refund_events WHERE created_at > now() - interval ''1 hour'''. 3) curl with idempotency key twice → second returns 200 + same event id."
If any section is vague ("it should work", "test thoroughly"), the lane reviewer must return verdict='changes-requested'.
When to call each tool
| Role | Call | When |
|---|
| Director | doc_create | After scoping an issue. Pass baseRevisionId on subsequent edits to avoid lost-update races. |
| Integrator (code lane) | doc_review with lane='code' | Reads the doc, checks scope realism + verification feasibility. |
| Integrator (quality lane) | doc_review with lane='quality' | Checks edge cases, test plan, risk inventory. |
| Integrator (devops lane) | doc_review with lane='devops' | Checks rollback, monitoring, deploy story. |
| Director | doc_approve | After all 3 lanes return verdict='approve'. The MCP refuses if any lane is changes-requested/block or missing. |
| Worker | doc_get with revision='approved' | Before writing any code on the issue. Pulls the sealed sections so the worker codes against an immutable spec. |
The MCP enforces (b) of doc_approve server-side: it queries design_doc_reviews for the active (non-superseded) verdicts on the revision and rejects if any lane ≠ approve. It also enforces (a): approverAgentId must equal PAPERCLIP_DIRECTOR_AGENT_ID env on the server.
Anti-patterns (auto-reject these)
- Vague verification — "test it works" is not a verificationStep. Demand commands, queries, or HTTP calls.
- Theatrical reviews — A lane reviewer who comments "looks good" without naming a specific risk that was checked is rubber-stamping. Reject the verdict and ask which specific failure modes were considered.
- Approving with one lane red — The Director should never call
doc_approve if aggregateLaneVerdicts shows a non-green lane. The MCP will refuse, but don't even try.
- Skipping
doc_get — A worker who starts coding without first calling doc_get with revision='approved' is operating off stale assumptions. Always re-pull the sealed revision.
- Editing scope mid-implementation — If reality forces a scope change, the Director must call
doc_create again (Paperclip auto-bumps revision_number), then re-run the 3-lane review on the new revision. Do not silently widen scope.
Soft-gate caveat (important)
This is a soft gate: the design-doc MCP records review/approval state, but it cannot stop a worker from coding without calling doc_get. Workers must voluntarily invoke doc_get before starting. Hard enforcement (Paperclip refusing checkout until an approval row exists) requires the Phase 4 Paperclip fork. Until then, treat this skill's discipline as load-bearing.
Storage at a glance
- Doc body lives in Paperclip (
PUT /api/issues/:issueId/documents/design-doc, JSON-encoded sections in body, baseRevisionId for versioning, auto-incrementing revision_number).
- Review/approval state lives in UltraThink Neon (
design_doc_reviews, design_doc_approvals).
- Review rows denormalize
paperclip_issue_id + revision_number so we can recover review history via the (issue_id, revision_number) tuple even if Paperclip's doc UUIDs reset on a fresh export/import.
