Spec-Driven Development

Purpose

This skill forces the agent to pause, analyze, and agree upon a specification before jumping into implementation code. Drafting a spec first prevents hallucinations, scopes down overly ambitious changes, and protects the codebase's existing architecture.

Task Classification — Run First

Before any other step, classify the task. The classification determines which gate path applies.

State the classification in one line before proceeding:

Classification: [Simple|Medium|Complex] — reason: <one sentence>

Simple Task — Assumption Log

For Simple tasks, skip the full spec. Instead, surface assumptions in a scannable 3-item max format and pause for user confirmation before any edit:

Trước khi bắt đầu, confirm 3 điều:

1. [Assumption về stack / file / scope] → đúng không? [y/n]
2. [Assumption về behavior / constraint] → đúng không? [y/n]
3. Scope: chỉ làm X, KHÔNG làm Y → đúng không? [y/n]

(Nếu có gì sai, nói ngay — tôi chờ trước khi tiếp tục.)

If any answer is "n" or ambiguous → reclassify as Medium and run Ground Truth Gate.

Ground Truth Gate — Required for Medium and Complex tasks

This gate must pass before a spec can be drafted or approved.

The agent must produce — and the user must explicitly confirm — all three documents:

Document 1: Data Model

List every entity involved in the feature. For each entity, specify field names, types, and constraints. No prose allowed — use a table or code block.

Entity: User
  - id: UUID, primary key
  - email: string, unique, not null
  - role: enum(admin, member), default=member
  - created_at: timestamp

Entity: Session
  - token: string, primary key
  - user_id: FK → User.id
  - expires_at: timestamp, not null

Gate check: If any field name, type, or relationship is written as "TBD", "flexible", or left blank → gate FAILS. Stop and fill in before continuing.

Document 2: Business Rules

List every logic condition that governs the feature. Use explicit if/then/else format. No prose paragraphs.

Rule 1: Login attempt
  IF email not found → return "Invalid credentials" (do not reveal which field failed)
  IF password wrong → return "Invalid credentials"
  IF account locked → return "Account locked, contact support"
  IF success → create Session, set HttpOnly cookie, redirect to dashboard

Rule 2: Session expiry
  IF Session.expires_at < now() → destroy session, redirect to login
  IF user is active within 30 min → extend expires_at by 30 min

Gate check: If any rule uses vague language ("handle appropriately", "validate properly", "standard logic") → gate FAILS. Rewrite as explicit condition before continuing.

Document 3: Acceptance Criteria

Every criterion must be in Given/When/Then format and be independently testable. Minimum 3 criteria per Medium task, 5 per Complex task.

AC-1:
  Given a registered user with correct credentials
  When they submit the login form
  Then a session cookie is set and they are redirected to /dashboard

AC-2:
  Given a wrong password is entered
  When they submit the login form
  Then "Invalid credentials" is shown and no session is created

AC-3:
  Given a session expired
  When the user navigates to any protected route
  Then they are redirected to /login and the expired session is destroyed

Gate check: If any criterion contains "works correctly", "as expected", "handles the case" → gate FAILS. Rewrite as specific observable outcome.

Out-of-Scope Declaration (required)

State explicitly what this feature does NOT do. Minimum 2 items.

Out of scope:
- Registration / sign-up flow
- Password reset
- OAuth / social login
- Rate limiting (tracked separately in SPEC-20260515-002)

Ground Truth Gate summary checklist — all must be ✅ before spec draft:

□ Data Model: all entities with field names, types, constraints — no TBDs
□ Business Rules: all conditions as if/then/else — no vague language
□ Acceptance Criteria: Given/When/Then, independently testable — no "works correctly"
□ Out-of-Scope: ≥ 2 explicit exclusions stated

If any checkbox is unchecked → STOP. Do not draft the spec. Return to the user with the specific gap.

Workflow (Strict Process)

ABSOLUTE DIRECTIVE: You are an Agent. You MUST NOT start writing implementation files (.ts, .js, .py, etc.) until you have completed this workflow and the user has explicitly approved the spec or the documented Fast Gate/Override Gate from using-sdd.

1. Context Analysis

• Review relevant files using Read, Glob, or Grep to understand the system boundaries.
• Identify how the proposed feature fits into the current architecture.
• Detect existing commands, test locations, project structure, and local conventions from repository files instead of inventing them.

2. Assumption Surfacing

• Before drafting spec content, explicitly list assumptions that affect scope, architecture, data, security, or verification.
• If an assumption materially changes the implementation path, ask a concise clarification question and stop until the answer is available.
• Do not silently fill in ambiguous requirements. Convert uncertainty into either an assumption, an open question, or a non-goal.

Example:

Assumptions:
1. This change targets the existing web UI, not a new API.
2. Authentication behavior remains unchanged.
3. Verification can use npm test plus a manual browser check.
Correct these before I proceed if any are wrong.

3. Draft the Spec

• Provide the user with a concise summary (1-3 paragraphs) containing:
• Core Objective: what is being built, why, and who it serves
• Assumptions & Open Questions: what is inferred, what still needs an answer, and what is out of scope
• Proposed Data/UI Flow: how data, state, and user interaction move through the system
• Success Criteria: specific, testable conditions that define "done"
• Boundaries: Always do, Ask first, and Never do constraints for this change
• Files to Modify & Files to Create: expected file scope and ownership boundaries
• Verification Method: exact test, build, lint, visual check, or manual check that will prove the change
• Pre-Code Gate: why this requires Spec Gate, Fast Gate, or Override Gate
• Reframe vague instructions as measurable success criteria before asking for approval.

Example:

Request: "Make the dashboard faster."
Success criteria:
- Dashboard initial load is measured before and after the change.
- The identified slow path improves by a named threshold or documented reason.
- Existing dashboard tests still pass.

#### Spec Artifact Template

For large, architecture-impacting, or multi-session work, propose a persistent spec file before implementation. Do not write it without user approval.

---
stage: [discovery|planning|implementation|verification|release]
tier: [T0|T1|T2|T3]
spec_id: SPEC-YYYYMMDD-XXX
---

# Spec: [Feature or Change Name]

## Objective
[What is being built, why, and who it serves.]

## Assumptions
- [Assumption that affects scope or architecture.]

## Success Criteria
- [Specific, testable condition.]

## BDD Acceptance
- Given [initial context]
- When [action or event]
- Then [expected outcome]

## Project Context
- Commands: [full commands with flags]
- Structure: [relevant directories and ownership boundaries]
- Style: [existing conventions or examples to follow]

## Proposed Flow
[Data, UI, API, state, or operational flow.]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Files
- Modify: [...]
- Create: [...]

## Verification
- [Exact command or manual check.]

## Open Questions
- [Question that must be answered before implementation, or "None."]

• Frontmatter is mandatory for persistent specs and must include stage, tier, and spec_id.
• BDD acceptance is mandatory for persistent specs and must include at least one Given/When/Then chain.

4. Task Breakdown

• Break the feature into granular, atomic checklist items ordered by dependency:

- [ ] Task 1: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [Exact test, build, lint, or manual check]
  - Files: [Expected files or bounded file area]

• Each task should be small enough for one focused implementation pass.
• If a task requires touching more than about five files, split it unless the files are tightly coupled and the coupling is explained.
• Mark parallelizable tasks explicitly only when they touch disjoint file areas and have clear integration boundaries.

5. Approval Gate

• End your response by asking the user for explicit approval: "Do you approve of this specification and task sequence? Please permit me to begin Task 1 (TDD)."
• If the user does not approve, stop. Do not begin TDD, do not edit tests, and do not edit production code.
• If the user approves, the next response before any edit must state:

Pre-code gate: Spec satisfied by user approval; next edit: <file>; verification: <command/check>.

Anti-Rationalizations

Be aware of lazy logic that an Agent typically uses to skip this step. If a thought on the left occurs, YOU MUST apply the rebuttal on the right:

Verification Gates

Do not conclude your first interaction turn unless you have fulfilled the following:

Classification & Ground Truth (run before spec):

• [ ] Task classified as Simple / Medium / Complex with stated reason.
• [ ] Simple: Assumption Log (≤ 3 items) presented and user confirmed before any edit.
• [ ] Medium/Complex: Ground Truth Gate passed — Data Model, Business Rules, Acceptance Criteria, Out-of-Scope all ✅.

Spec content:

• [ ] Displayed the Spec structure and Task Checklist to the user.
• [ ] Surfaced assumptions, open questions, and non-goals.
• [ ] Reframed vague requirements as specific, testable success criteria.
• [ ] Included the Pre-Code Gate and Verification Method.
• [ ] Included task-level Acceptance, Verify, and Files fields when tasks are listed.
• [ ] Explicitly checked for side-effect risks on the existing infrastructure.
• [ ] Requested strict explicit approval from the user to proceed.
• [ ] Made no test or production edits before approval.

Edge Cases

• [Massive Feature Request]: If the feature requires touching >10 files, immediately raise a RED FLAG. Stop and request a scope reduction from the user before finalizing the spec.
• [Architectural Violation]: If the user's request violates underlying framework patterns (e.g., securely calling a database from a Next.js Client Component), stop and suggest a corrected architectural spec.
• [Spec Drift]: If implementation evidence, platform reality, or user feedback contradicts an approved spec, pause and route through spec-evolution before continuing.
• [Persistent Spec Needed]: If work is likely to span multiple sessions or reviewers, propose saving the spec in the repository. Ask before writing and do not commit without explicit user approval.

Related Skills

• source-driven-development - Used when the spec depends on official framework, library, API, or platform behavior.
• planning-and-task-breakdown - Used for ultra-large epics that need more project management than a compact technical spec.
• test-driven-development - Invoked immediately after the Spec is approved to implement Task 1 using the Red-Green-Refactor cycle.
• spec-evolution - Used when an approved spec conflicts with implementation reality, tests, review findings, user feedback, or platform constraints.