Actionable Development Design

Requirements

For Codex-class agents with repository and file access. Note that files do not provide browser, testing tools, credentials, project data, or permission to modify external systems; other hosts may require adaptation.

Confirmed requirements, decisions, acceptance conditions, and related samples
Accessible repository rules, actual code, structure and migration information, and existing documentation
Complete product design requires deliverable reference documents from develop-closed-loop; new page designs require frontend-design-lab not included with the package
Key mechanism judgments require obtainable implementation evidence or moderate authorized checks; mechanism probes do not replace business acceptance.

Quick start

After downloading, first check the package instructions, then extract the ZIP to a staging directory.
When installing the collection, copy the six Skill folders and the sibling shared folder to the project's .agents/skills/ or personal ~/.agents/skills/. Maintain the relative directory structure; do not treat the collection's outer directory as a single Skill to install.
When installing a standalone ZIP, place its same-named folder into the chosen Skills directory and preserve its internal shared resources. Back up same-named Skills before overwriting to avoid duplicate installation.
Use the exact $write-design-doc call in Codex; if not discovered, restart the host. If the task requires process handoff, install the corresponding supporting Skill separately.

Applicable Scenarios

Prepare development designs before implementing confirmed requirements.
Review existing designs for reuse assumptions, missing entry points, contract conflicts, and recovery uncertainties.

Usage Steps

Fix scope, authoritative sources, decisions, real samples, and applicable entry points. Choose verification depth based on actual risk; clear local changes can use a short design.
Trace back from mechanisms to be reused or modified to callers and consumers, including bypasses, background tasks, and other outputs; document the ownership of each affected entry point.
Verify key guarantees such as priority, compatibility, idempotency, atomicity, and recovery through actual implementations, existing checks, or authorized minimal isolation mechanism experiments.
Connect input, validation, branching, state, persistence, visible results, and failure recovery with a set of authoritative contracts. Field names should be common and consistent; retain necessary feedback; only add explanatory page copy if explicitly requested by the user.
Walk through normal, rejection, and recovery scenarios continuously, challenging assumptions with relevant counterexamples; after revision, re-verify affected contracts, callers, and results.
Finally, determine readiness, separately explaining document completeness, contract consistency, and mechanism feasibility; report READY FOR IMPLEMENTATION, PARTIALLY READY, or BLOCKED with limitations based on evidence.

Deliverables

Development design and applicable database/interface documentation in the project's .talking-us/ or existing authoritative location.
REQ/AC mapping, ownership of affected entry points, key mechanism evidence, explicit unknowns, and acceptance to be executed after implementation.
Design verification reference, field and copy sharing rules, and seven sets of evaluation samples and independent criteria for maintenance use only.

Limitations

Does not implement products, modify configuration or business data, execute migrations, or auto-publish. Read-only checks and isolation mechanism experiments are constrained by existing authorization and do not produce business side effects.
Mechanism probes are not equivalent to real business acceptance. Future implementations lacking operational acceptance do not themselves block design readiness; core guarantees that remain unverified cannot be considered overall ready.
Parseable documents, existing links, or a large number of use cases do not equate to mechanism feasibility or cross-model reliability. Evaluation samples are for maintenance, not a mandatory item for every project design.

Example Prompts, Not Actual Execution Cases

Use $write-design-doc, combining repository review with approved export design. Trace back all callers and consumers, verify retry and compatibility assumptions with currently available evidence, walk through failure recovery counterexamples and revise authoritative contracts. Report readiness status and unverified boundaries, without implementing functionality or executing migrations.

Inside the skill

SKILL.md

---
name: write-design-doc
license: MIT
description: >-
  Write or review implementable development, database, and API designs from confirmed requirements and the actual project. Verify critical mechanisms, cross-layer contracts, and failure recovery before judging handoff readiness.
  Clarify missing product decisions first. Deliver design only; do not automatically develop the product or execute migrations.
---

# Implementable Development Design

Enable developers to implement from the design and understand the basis and limits of critical technical judgments. Document completeness, specification consistency, and mechanism feasibility are separate checks. State evidence for all three when judging readiness.

Maintain this task's design and authorized project documents, without changing product code, configuration, business data, or deployment. Within existing authorization, inspect current behavior, run existing targeted checks, or conduct minimal mechanism experiments without business side effects in a temporary isolated directory. This does not authorize real-data writes, paid external calls, or complete feature development.

## 1. Fix Scope and Choose Verification Depth by Risk

Included files · 12

write-design-doc/LICENSE
write-design-doc/MANIFEST.json
write-design-doc/README.md
write-design-doc/SKILL.md
write-design-doc/agents/openai.yaml
write-design-doc/evals/cases.md
write-design-doc/evals/rubric.md
write-design-doc/references/design-invariants.md
…