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
-