spec

Spec

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

When to Use

• Starting a new project or feature
• Requirements are ambiguous or incomplete
• The change touches multiple files or modules
• You're about to make an architectural decision
• The task would take more than 30 minutes to implement

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

Process

Read the ## Confirmed Intent section from the spec file as locked input. If it's missing or empty, stop and invoke interview-me first — the confirmed intent is a prerequisite, not something to redo here.

Surface assumptions immediately. Before writing any spec content, list what you're assuming:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.

Write a spec covering these six core areas:

1. Confirmed Intent — Locked input from interview-me. Read it from the spec file's first section; do not edit here.

2. Commands — Full executable commands with flags, not just tool names.

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev
   

3. Project Structure — Where source code lives, where tests go, where docs belong.

   src/           → Application source code
   src/components → React components
   src/lib        → Shared utilities
   tests/         → Unit and integration tests
   e2e/           → End-to-end tests
   docs/          → Documentation
   

4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.

5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.

6. Boundaries — Three-tier system:

   • Always do: Run tests before commits, follow naming conventions, validate inputs
   • Ask first: Database schema changes, adding dependencies, changing CI config
   • Never do: Commit secrets, edit vendor directories, remove failing tests without approval

Spec template:

# Spec: [Project/Feature Name]

## Confirmed Intent
[Locked input from `interview-me`. Do not edit here without re-running `interview-me`.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

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

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.

Downstream consumers

Specs are read by the plan skill (which produces an implementation plan) and by implementation agents that execute against that plan. Write the spec rich enough to support both:

• Every six core areas filled — thin sections produce thin plans
• Success criteria testable — "LCP < 2.5s on 4G" not "faster"
• Boundaries explicit — Ask First and Never lists prevent silent scope creep mid-build

A thin spec produces a thin plan and a confused implementer.

Keeping the Spec Alive

The spec is a living document, not a one-time artifact:

• Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
• Update when scope changes — Features added or cut should be reflected in the spec.
• Commit the spec — The spec belongs in version control alongside the code.
• Reference the spec in PRs — Link back to the spec section that each PR implements.

Common Rationalizations

Rationalization	Reality
"This is simple, I don't need a spec"	Simple tasks don't need long specs, but they still need acceptance criteria. A two-line spec is fine.
"I'll write the spec after I code it"	That's documentation, not specification. The spec's value is in forcing clarity before code.
"The spec will slow us down"	A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.
"Requirements will change anyway"	That's why the spec is a living document. An outdated spec is still better than no spec.
"The user knows what they want"	Even clear requests have implicit assumptions. The spec surfaces those assumptions.

Red Flags

• Starting to write code without any written requirements
• Asking "should I just start building?" before clarifying what "done" means
• Implementing features not mentioned in any spec or task list
• Making architectural decisions without documenting them
• Skipping the spec because "it's obvious what to build"

Verification

Before proceeding to implementation, confirm:

• The spec covers all six core areas
• The human has reviewed and approved the spec
• Success criteria are specific and testable
• Boundaries (Always/Ask First/Never) are defined
• The spec is saved to a file in the repository