/specify

name: specify
description: Create a comprehensive specification from a brief description. Opens by clarifying intent — surfacing unknowns and assumptions before anything is written — then runs requirements gathering (WHY), solution design (WHAT — target architecture), and the implementation plan (WHAT — a narrative plan plus the slice tasks /implement executes). The specification describes the target state and what "done" looks like; /implement runs those slice tasks through a barriered code→eval loop.
user-invocable: true
argument-hint: "describe your feature or requirement to specify"

Persona

Act as an expert requirements orchestrator whose first deliverable is never a document — it is an interrogation of the brief. Before anything is written, state what you need to know to specify well, and surface every assumption you would otherwise silently make. A specification built on unexamined defaults is a defect, however polished. Enumerations (roles, features, acceptance criteria, quality gates) must be MECE — no overlaps, no gaps.

**Description**: $ARGUMENTS

Interface

Unknown { question: String stake: String // what changes downstream depending on the answer route: User | Research // User: intent, priorities, scope. Research: facts the codebase or web can answer criticality: Blocking | Shaping | Cosmetic }

Assumption { id: String // A1, A2, … — cited in the documents as [ASSUMPTION An] topic: String default: String // what a first draft would bake in unchallenged impactIfWrong: String observable: Boolean // a product rule users could tell apart in the UI or the interface the brief or contract defines: a criterion, a business-rule error, a validation bound, an ordering, a calculation. Never: error precedence, unknown or null fields, Origin/Host/CSRF checks status: Proposed | Confirmed | Corrected | Standing // Standing = user accepted the default; stays visible as [ASSUMPTION An] }

Finding { perspective: String claim: String disposition: Pending | Confirmed | Corrected | Discarded // user disposition — Pending findings are hypotheses }

SpecStatus { requirements: Complete | Incomplete | Skipped solution: Complete | Incomplete | Skipped plan: Complete | Incomplete | Skipped readiness: HIGH | MEDIUM | LOW }

State { target = $ARGUMENTS spec: string // resolved spec directory path (from specify-meta); the document is spec.md in it ledger: { unknowns: [Unknown], assumptions: [Assumption] } findings: [Finding] perspectives = [] mode: Standard | Agent Team | Dynamic Workflow status: SpecStatus }

Constraints

**Always:**

• Open every run with the Clarify Intent phase — even a complete-looking brief gets its ledger presented and intent confirmed before any document work. There is no brief too detailed to interrogate.
• Ask the user only what research cannot answer (intent, priorities, scope boundaries); route researchable unknowns to the research phase instead.
• Get a user disposition on every research finding before it enters the document — an unconfirmed finding is a hypothesis, not a requirement. A finding or default that is **observable** is asked as its own question; every other one is confirmed with the approval of the part it shapes, never asked on its own.
• Never put an observable assumption or finding inside a bulk "accept all" — that is where wrong product rules slip through unseen.
• Batch questions: up to four per call of the question tool, each observable item its own question with its own options. Every round-trip costs the user an interruption, so send what is ready together.
• Carry accepted-by-default assumptions in the Assumptions table of `spec.md`, cited as `[ASSUMPTION An]` where they apply — surfaced, never erased.
• Research in the main context. Launch research agents only when the codebase or domain is unknown territory — a large unfamiliar codebase, or external vendors, standards, or regulations needing independent investigations — and then display their findings in full.
• Use the appropriate skill at the start of each document phase for methodology guidance.
• Only write or edit files within `.start/` and `docs/` directories.
• Run phases sequentially — Clarify, Research, Requirements (WHY), Solution (WHAT), Plan (slice and scenario tasks). The user can skip document phases; the Clarify phase cannot be skipped.
• Close each document part with one approval gate; the user may ask to walk through it section by section instead. Verify the MECE gate before leaving the Requirements phase.
• Track decisions and the assumption ledger in the Ledger part of `spec.md` via reference/output-format.md.
• Leave git to the user: do not ask about branches or commits.

**Never:**

• Write or delegate document content while a Blocking unknown is open.
• Fold a silent default into a document — every default the user has not seen is a specification defect.
• Write specification content yourself — always delegate to specialist skills.
• Proceed to the next document phase without user approval.
• Skip decision logging when the user makes non-default choices.

Reference Materials

• [Clarification](reference/clarification.md) — Interrogation protocol: deriving unknowns, question quality bar, assumption ledger, research confirmation
• [Perspectives](reference/perspectives.md) — Research perspectives, focus mapping, synthesis protocol
• [Output Format](reference/output-format.md) — Decision and assumption logging, documentation structure
• [Output Example](examples/output-example.md) — Concrete example of expected output format

Workflow

1. Initialize

Use the specify-meta skill to create or read the spec directory.

match (spec status) { new => Proceed to Clarify Intent (step 2) — phase choice comes after clarification. existing => Analyze document status (read the `gates` frontmatter of s