# Spec

> Turn a vague feature or product idea into an agreed, persisted specification through relentless structured questioning. Never assumes — every gap, ambiguity, or "probably" becomes a question to the developer, and the spec cannot be approved while open questions remain. Produces docs/specs/<NNN>-<slug>.md with acceptance criteria that /plan, /scaffold, and /tdd consume. Use when: "spec", "write a spec", "spec this out", "requirements", "PRD", "acceptance criteria", "define the feature", "user stories", "what should we build", or before planning any feature too big to describe in one sentence.

- Skill: `codewithmukesh/spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add codewithmukesh/spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codewithmukesh/spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: codewithmukesh (https://skillmd.com/u/codewithmukesh)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/codewithmukesh/spec

---


# /spec — Relentless Specification Workflow

## What

Converts an idea into a written, versioned specification that both the developer
and Claude explicitly agree on — before any planning or code. The contract:

- **Never assume.** Every gap in the idea becomes a question. If Claude catches
  itself thinking "probably", "presumably", or "the usual way" — that thought is
  a question to ask, not a decision to make.
- **Relentless, but structured.** Questions come in focused rounds (3–5 at a
  time) across nine dimensions — not one overwhelming dump, and not a single
  polite round that stops early.
- **Agreement is explicit.** Specs have a status lifecycle: Draft → In Review →
  Approved. Implementation never starts from a Draft. Approval requires the
  developer to read the final document and say so.
- **Specs are files, not chat.** Output persists to `docs/specs/<NNN>-<slug>.md`
  and survives the session. Plans, tests, and commits reference it.

## When

- Any feature too big to describe completely in one sentence
- New product or module ideas ("I want to add team workspaces")
- Before `/plan` for non-trivial features — plan consumes the approved spec
- When requirements feel fuzzy mid-implementation: stop, `/spec`, re-plan
- Trigger phrases: "spec", "requirements", "PRD", "define the feature", "acceptance criteria"

**Skip for:** bug fixes, refactors, single-endpoint CRUD where the entity is obvious.

## How

### Step 1: Capture and Restate

Take the raw idea and restate it in one paragraph: what Claude understood, in its
own words. End with: "Is this the idea? What did I get wrong?" Do not begin
questioning until the developer confirms the restatement — questioning the wrong
idea wastes everyone's time.

### Step 2: Questioning Rounds

Work through the nine dimensions in order. Each round: pick the 3–5 most
load-bearing unanswered questions (answers that reshape later questions come
first). Where the harness supports selectable options, present choices with
trade-offs — and a recommendation — but **the developer chooses; a recommendation
is never silently applied**.

| # | Dimension | What to pin down |
|---|-----------|------------------|
| 1 | Problem & users | Who hurts today, how they work around it, what success looks like |
| 2 | Scope | What is IN this iteration, what is explicitly OUT, where the MVP line sits |
| 3 | Domain & data | Entities, relationships, lifecycle (create→archive→delete?), retention |
| 4 | API contract | Resources, endpoints, request/response shapes, pagination, versioning |
| 5 | Authorization | Who can do what, role/claim model, tenant boundaries |
| 6 | Edge cases & failure modes | Concurrency, duplicates, idempotency, partial failure, limits |
| 7 | Non-functionals | Expected volume, latency budget, growth assumptions |
| 8 | Integrations | External services, published events, webhooks, side effects |
| 9 | Acceptance criteria | Testable Given/When/Then for every behavior in scope |

**Rules of relentless questioning:**

- Record every answer in the draft spec immediately — answers are requirements, not conversation.
- Challenge contradictions on the spot: "In round 1 you said X; this answer implies not-X. Which wins?"
- "I don't know" is a legal answer → moves to **Deferred Decisions** with an explicit
  fallback the developer chooses now ("default to soft-delete until decided").
  Silent deferral is forbidden.
- A dimension is done when a follow-up round generates zero new questions for it.
- The questioning phase is done when ALL nine dimensions are done. Do not stop
  because the conversation feels long — stopping early is how assumptions sneak in.

### Step 3: Draft the Spec File

Determine the next number from existing files in `docs/specs/` (create the
directory if missing). Write `docs/specs/<NNN>-<slug>.md`:

```markdown
# Spec NNN: <Title>

**Status:** Draft
**Date:** <today>

## Problem            <!-- who hurts, why now -->
## Scope              <!-- ### In / ### Out — both explicit -->
## Domain Model       <!-- entities, relationships, lifecycle -->
## API Contract       <!-- endpoints table: verb, route, request, response, errors -->
## Authorization      <!-- who can do what -->
## Edge Cases & Failure Modes
## Non-Functional Requirements
## Integrations
## Acceptance Criteria  <!-- Given/When/Then, numbered AC-1, AC-2, ... -->
## Deferred Decisions   <!-- decision, chosen fallback, revisit trigger -->
## Open Questions       <!-- MUST be empty before approval -->
```

### Step 4: Review Loop

Set status to **In Review**. Present the complete spec and ask: "Read this
end-to-end. What is wrong, missing, or over-engineered?" Fold corrections in and
re-present. Repeat until the developer has no further changes. New answers may
spawn new questions — that is the process working, not a failure to converge.

### Step 5: The Agreement Gate

Approval is a deliberate act, never inferred from silence or "looks good" in
passing. Ask explicitly: "Do you approve this spec? After approval, code follows
the spec — changes go through the spec first." On approval, set
`**Status:** Approved (<date>)`.

- **Open Questions must be empty.** If any remain, the spec cannot be approved — resolve or defer each one explicitly.
- If implementation later reveals a wrong assumption: stop, set status back to
  In Review, fix the spec with the developer, then resume. Code never silently
  diverges from an approved spec.

### Step 6: Handoff

- `/plan` reads the approved spec and maps acceptance criteria to implementation steps
- `/tdd` turns acceptance criteria into the first failing tests (AC-n → test name)
- Commits for the feature reference the spec: `feat: team workspaces (spec 004)`

## Example

```
User: /spec users should be able to invite teammates

Claude: Here's what I understood: an existing user can invite another person
  to join their... workspace? account? That's already my first gap.
  Is this the idea? What did I get wrong?

User: yes, invite to their organization

Claude: Round 1 — Scope & Users:
  1. Can invitees be people without an existing account, or only registered users?
  2. Who can invite — any member, or only admins/owners?
  3. Is there a limit on pending invites (per org, per plan)?
  4. Out of scope check: bulk invites and SSO-provisioned members — both OUT for now?

User: 1: both. 2: admins only. 3: no limit. 4: correct, both out.

Claude: Round 2 — Edge cases (your "both" in Q1 raises these):
  1. Inviting an email that already has a pending invite — error, or resend?
  2. Invite expiry — 7 days, 30 days, never?
  3. Invitee already belongs to another org — multi-org membership or rejection?
  ...

[…rounds continue until all nine dimensions are exhausted…]

Claude: Spec written to docs/specs/004-team-invitations.md (In Review).
  Read it end-to-end. What is wrong, missing, or over-engineered?

User: looks right. approved.

Claude: Status: Approved (2026-06-12). Next: /plan to map AC-1..AC-9
  to implementation steps.
```

## Related

- `/plan` — Consumes the approved spec; never plan a spec-worthy feature without one
- `/tdd` — Acceptance criteria become the first failing tests
- `/scaffold` — Generates the slices the plan calls for
- `architecture-advisor` — Load during Step 2 if the feature forces architectural decisions