spec-driven-development

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.

Class	Criteria	Gate path
Simple	≤ 1 file, ≤ 30 min, intent unambiguous, no data model change	Assumption Log (≤ 3 items) → Fast Gate → code
Medium	Multi-file, ≤ 2 days, some data or logic change	Ground Truth Gate → Spec Gate → plan → tdd
Complex	Cross-domain, > 2 days, new entities, auth, billing, or architecture change	Interview Gate → Ground Truth Gate → Spec Gate → plan → tdd

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