specify

name

specify

description

Guide the user through a structured specification process: define the goal, specify exactly what to build (and what NOT to build), and establish measurable evaluation criteria — all before implementation begins. Produces a living spec document. Use when the user has a goal or feature idea and wants to define the spec, says "specify this", "what's the spec", "define the specification", "how do I achieve this goal", "break this down", "what do I need to build", "write a spec", "define requirements", wants to create a specification with verification criteria, or has just finished using the-goal and wants to turn the goal into a precise, implementable specification. Also use when the user wants to define evaluation criteria before coding, or mentions "adversarial verification", "quality criteria", or "acceptance criteria".

Specify

Guide the user through a structured specification in three phases — Goal, Specification, Evaluation Criteria — producing a single living document that defines exactly what to build, what not to build, and how to verify the result.

Skill workflow: the-goal (find the real goal) → specify (define the specification) → implementation

---

Core behavior

Interview pattern — the same in every phase

All three phases use the same interview approach:

Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. Ask one question at a time using your runtime's interactive prompt tools. Before each question, show your preference ranking: list the likely answers ordered by your recommendation (best first), with a one-sentence reason for your top pick. Offer these as choices when prompting the user.

After each answer, restate the decision explicitly and confirm before moving on. Never assume — verify.

Scope discipline — enforced in every phase

Monitor the growing specification continuously. When the document becomes too large — too many features, too many tasks, too many evaluation criteria — push back hard. Insist that scope must be reduced. The user decides what to cut, but you insist that something must go. Challenge with:

• "This is growing beyond what can be built and verified reliably. Which of these can we leave out of this spec and handle separately?"
• "Can this be two specs instead of one? What's the minimum that delivers the goal?"

This applies equally across all three phases. A goal that's too broad, a feature list that's too long, or an evaluation plan that's too complex — all get the same pushback.

---

Phase 1: Goal

Establish the goal using the interview pattern above. If a goal document already exists from a prior the-goal session, read it and confirm with the user. If the user has a rough idea but no document, interview to extract:

• What & Why — the goal and why it matters
• Done Looks Like — the finished behavioral state: user journeys, observable outcomes (not feature names)
• Boundaries — what is explicitly out of scope

If the goal is genuinely vague or too broad, recommend running the-goal skill first rather than trying to specify something unclear.

Push back if the goal tries to solve multiple problems at once: "Is this one goal or several? Which single outcome matters most?"

---

Phase 2: Specification

Before interviewing, explore the codebase with a subagent to understand the existing landscape — architecture, patterns, schemas, testing frameworks, relevant modules. Come prepared with context so the user doesn't have to explain what you can discover yourself.

Then interview through each section, one at a time:

a. Scope Boundaries

Now that the goal is defined, draw the line. Interview to establish:

• In scope — what will be built, changed, or delivered
• Out of scope — what will NOT be built, with a reason for each exclusion

Every boundary must be a conscious decision. Challenge anything implicit: "You didn't mention X — is that intentionally out of scope, or did we miss it?" Nothing is assumed in or out — everything is explicitly stated.

b. Constraints & Assumptions

What are we building with and within? Interview to separate:

• Hard constraints (non-negotiable) — tech stack, API rate limits, performance requirements, security mandates, deployment targets
• Assumptions (believed true but not verified) — library behavior, data volumes, user behavior patterns

For each assumption, ask: "What happens if this turns out to be wrong? Should we verify this first?"

c. Decisions Already Made

What's already decided and shouldn't be revisited? Document:

• Database schemas in use
• Encryption standards
• Architectural patterns
• API contracts
• Naming conventions
• Library choices

These are guardrails. They constrain the solution space and prevent the implementer from relitigating settled decisions.

d. Task Breakdown

Decompose the work into discrete, independently verifiable sub-tasks. Each task is a checkpoint — a clear deliverable. Interview to ensure each task is:

• Small enough to complete and verify in a single session
• Independent enough to verify on its own
• Concrete enough to know when it's done
• Ordered so each builds on the last, with blockers marked

Definition of Done and Evaluation are MANDATORY for every task. For each task, you MUST explicitly define:

1. Done When (Definition of Done) — The observable completion criterion. NOT "code is written" or "feature is implemented". ASK:

   • "What specific state or behavior proves this task is complete?"
   • "If you walked away and came back tomorrow, what would you check to verify this is done?"
   • "What would you show me to demonstrate completion?"

2. Evaluation Criteria — The specific checks that verify this task is done correctly. Link each task directly to its verification. ASK:

   • "What deterministic check proves this task works? A test that passes? A command that succeeds? A file that exists?"
   • "If this task has no automated check, what would you judge manually? What's the rubric?"
   • "On a scale of 1–5, what does 'good enough' look like for this task? What's the minimum acceptable score?"

Push back hard if:

• A task has no clear Definition of Done ("when the code is written" is NOT a DoD)
• A task has no evaluation criteria (every task must be verifiable)
• A DoD is vague or subjective without a corresponding LLM-as-judge rubric
• The user says "we'll figure out testing later" (evaluation criteria are defined NOW, not later)

Make DoD and evaluation criteria first-class concerns. They are not optional metadata — they ARE the spec. A task without a clear DoD and evaluation criteria is not a task, it's a wish.

These are the deliverables. Each one must be independently demoable, verifiable, and measurable.

---

Phase 3: Evaluation Criteria

This phase defines how to verify the implementation is correct — before any code is written. The criteria become the quality contract.

Interview the user to define two categories of checks:

a. Deterministic checks

Automated, pass/fail verification that runs without judgment:

• Scripts or commands that produce a clear pass/fail
• Schema validations
• Test assertions
• Output comparisons
• Performance thresholds (response time < Xms, memory < Y MB)

For each task in the breakdown, ask: "What's a concrete check that proves this task is done correctly?" Push hard toward deterministic checks — they're cheaper, faster, and more reliable than judgment.

b. LLM-as-judge criteria

For aspects that can't be automated, define measurable rubrics that a model can evaluate. Each criterion must have:

• Question — a clear question the judge must answer (e.g., "Does the error message explain what went wrong and how to fix it?")
• Evidence — what the judge should examine (e.g., "Read all error messages produced by the module")
• Scale — a measurable threshold or rubric (e.g., "1–5 scale where 5 = message explains cause, consequence, and fix action")
• Pass boundary — minimum score to pass (e.g., "≥ 4")

For every criterion the user describes subjectively, push to make it measurable: "How would you score this on a 1–5 scale? What's the minimum acceptable score?"

c. Adversarial verification protocol

The spec must instruct that verification is adversarial: the model that implements is NOT the model that verifies. Include in the spec:

• The verifier evaluates against the criteria defined above
• The verifier produces a verdict for each criterion (pass/fail with evidence)
• The verifier identifies issues the implementer should address

d. Convergence criterion

Define when the implementation loop should stop. The implementing agent keeps iterating as long as further modifications are cost-effective — that is, the expected improvement in evaluation score justifies the cost of another iteration. The spec should define:

• Quality floor — minimum scores that must be met (hard stop below this)
• Diminishing returns signal — e.g., "Stop when the last iteration improved less than N% on any criterion"
• Maximum iterations — an upper bound to prevent infinite loops

---

Output

Write the specification using the template below. Save to ./specs/<feature-name>.md. Create the ./specs/ directory if it doesn't exist.

Present the complete spec to the user for final review. Ask:

• "Does each section accurately capture what we discussed?"
• "Are there gaps — things we know but didn't cover?"
• "Are the evaluation criteria tight enough to catch real problems?"

Iterate until the user confirms. Remind them this is a living document — update it as implementation reveals new information.

Spec:

Goal: Date: Status: Draft | Active | Complete

---

What & Why

The goal and why it matters.

Done Looks Like

The finished behavioral state. Describe as user journeys and observable outcomes:

• Outcome 1 — description of observable behavior
• Outcome 2 — description of observable behavior

---

Scope

In Scope

• Item — description
• Item — description

Out of Scope

• Item — reason for exclusion
• Item — reason for exclusion

---

Constraints & Assumptions

Hard Constraints

• Constraint — description

Assumptions

• Assumption — what happens if wrong

---

Decisions Already Made

Decision	Rationale
Decision	Why

---

Task Breakdown

Task 1:

• Depends on: none
• Description: what to do
• Done when: <observable completion criterion — specific state or behavior that proves completion>
• Evaluation:
  • Deterministic check: <command/test that must pass> →
  • LLM-as-judge (if applicable): → <1-5 scale: what does each score mean> → Pass ≥

Task 2:

• Depends on: Task 1
• Description: what to do
• Done when: <observable completion criterion — specific state or behavior that proves completion>
• Evaluation:
  • Deterministic check: <command/test that must pass> →
  • LLM-as-judge (if applicable): → <1-5 scale: what does each score mean> → Pass ≥

---

Evaluation Criteria

Note: Each task above includes its own evaluation criteria inline. This section aggregates all criteria into verification tables for the implementing and verifying agents.

Deterministic Checks

Check	Task	How to run	Pass condition
Name	Task N	Command/script	Expected result

LLM-as-Judge Criteria

Criterion	Task	Question	Evidence to examine	Scale	Pass boundary
Name	Task N	Question the judge answers	What to look at	1–5 scale definition	≥ N

Verification Protocol

• Adversarial: The verifying model MUST be different from the implementing model.
• Process: Verifier evaluates every criterion above, produces pass/fail with evidence for each, and identifies issues for the implementer.

Convergence

• Quality floor: All deterministic checks pass. All LLM-as-judge criteria meet their pass boundary.
• Diminishing returns: Stop when the last iteration improved less than % on any criterion.
• Max iterations:

The skill's work is complete when the spec has been saved and the user has confirmed it. Return control to the user.