القائمة
Use when starting any non-trivial feature or project, or when docs and code have drifted — write the design chain before or alongside code and reconcile specs onto reality.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when wiring a project's dev workflow (local stack, test tiers, gates, docs), or when naming make targets in a repo that has siblings — build a thin self-documenting Makefile facade over real scripts, name targets from the shared cross-repo vocabulary, and split env files by owner so targets consume them but never write them.
Use when you need to prove a feature actually delivers its intended outcome to a user or caller, not just that its code paths run — write executable acceptance tests against real, observable outcomes, derived from the spec before or independent of the implementation.
Use when adding any new capability to a working system — ship it behind a flag or optional collaborator that defaults to prior behavior.
Use when a spec, plan, or implementation must be independently reviewed before it is trusted, committed, or advanced to the next phase — dispatch a fresh reviewer per named lens whose job is to refute the artifact, not confirm it.
Use when building automation that edits, tests, or deploys itself — an agent that regenerates its own code, a self-updating pipeline, any loop that modifies the thing running it.
Use when about to call any integration, deployment, or hard guarantee "done" — prove it live end-to-end and capture the run as evidence.
| name | spec-driven-development |
| description | Use when starting any non-trivial feature or project, or when docs and code have drifted — write the design chain before or alongside code and reconcile specs onto reality. |
Author an ordered design chain — BRIEF → RESEARCH → SPECS → DESIGN → TASKS — before or alongside writing implementation code, then keep those specs reconciled onto the code that actually shipped. The chain is not ceremony: each phase feeds the next, and the specs stay alive as versioned artifacts after launch.
Reach for this when:
Red-flag thoughts that mean STOP and apply this skill:
Code written without a spec encodes decisions you never examined; the design doc you back-fill afterward just rationalizes whatever you happened to type. Separating what from how lets reviewers catch a wrong requirement before you've spent days building the right mechanism for it. Recording verdicts in the doc means a settled debate stays settled — re-opening it in the next phase burns time and erodes trust in the chain. And a spec that freezes at its original optimistic claims becomes a lie the moment code diverges: the next person reads it, believes it, and builds on a fiction. Reconciling the spec onto reality keeps the document worth reading, which is the only thing that keeps it being read.
On the project this was distilled from — a hexagonal, human-in-the-loop AI agent shipped to a cloud platform — the docs/BRIEF.md header literally carried its place in the chain: "Status: Approved — feeds SPECS → DESIGN → TASKS → TDD build." RESEARCH closed with a peer-review addendum (§12) whose verdict, "ACCEPT-WITH-NOTES," was then "carried into SPECS/DESIGN (they refine the design; they are not re-research)" — the notes moved forward as refinements rather than being re-argued. After launch, when the build diverged from the plan, the team didn't abandon the docs: SPECS went to v0.4 and DESIGN to v1.4, "reconciled to delivered code — HTTP API + observability un-deferred, decision thresholds now YAML-tunable." The specs described what actually ran. You can apply all of this on any stack: name your phases, review each, version the specs, reconcile after divergence.
What a machine can check: the chain's structure, not its wisdom. A spec-structure lint — every phase doc carries a status line and a recorded review verdict, every phase names the doc it consumes, cross-links resolve — plus a version bump asserted when a spec's content changes. The judgment inside a phase is gated by the independent review the rule already requires (adversarial-lens-review is its binding form), with the verdict recorded where the lint can find it.
