Spec First

spec-first

**Better code from AI. Fewer rewrites. One file. Works with any tool.**

Before writing code, your AI writes a short plan — what can break, what other features are affected, what "done" looks like. The AI didn't get smarter — it got a planning step.

Two developers. 24 days. Same AI tools — but with planning first. Fix:feat ratio: 5:1 → **1.5:1** — the AI stopped generating bugs at the rate it generated code. 65% fewer failed code reviews. These aren't projections — they're from [626 production commits](#evidence).

What you get

Without spec-first	With spec-first
AI skips error states — they fail in production	Failure cases caught before code is written
Broken integrations — AI forgot what else exists	Changes stay in scope — other features stay intact
"Looks good" from the AI that just wrote the code	A second pass catches what the builder missed
Third variation of the same wrong fix	Fixed in one try because root cause is identified first
Messy codebase? AI hallucinates what's there	Map what actually exists, then fix it section by section

**Better code quality. Better organization. Safer refactoring. Faster shipping.**

What a spec actually looks like (click to expand)

# Feature: Password Reset

## S1: Error States (failures FIRST — happy path last)
| Condition | User sees |
|-----------|-----------|
| Email not found | "Check your email" (same message — don't leak which emails exist) |
| Token expired (>1hr) | "This link has expired. Request a new one." + link |
| Token already used | "This link has already been used." |
| New password = old password | "New password must be different from current password." |
| ✅ Happy path | Email sent → user clicks → sets new password → redirected to login |

## S3: Cross-Feature Integration
| Feature | How it's affected |
|---------|-------------------|
| Login page | Add "Forgot password?" link |
| Email