Spec Blueprint

Spec Blueprint

A four-phase process for turning a rough idea into an implementation-ready plan. Each phase produces an artifact the next phase builds on. Don't skip phases or collapse them together, the whole point is that each one forces a level of clarity the next phase depends on.

Why this process works

Ideas arrive underspecified. If you jump straight to "here's a plan," you end up guessing at requirements the user actually has opinions about, and the resulting spec is generic. Asking one question at a time, rather than dumping a giant intake form, keeps the user actually thinking about each answer instead of skimming and picking defaults. It also lets each question build on the last, so by the end you have a spec shaped by a real conversation, not a template with blanks filled in.

Similarly, jumping straight from spec to "write the code" skips the sizing problem: steps that are too big produce sprawling, hard-to-review changes; steps that are too small waste time on ceremony and never accumulate into working software. The explicit "draft chunks, then break into smaller steps, then review for right-sizing" loop in Phase 3 exists because getting step size right on the first pass is hard, it's a designed-in second look.

Phase 1: Interactive brainstorming

Ask the user one question at a time to develop the spec. Requirements:

• Exactly one question per message. Never bundle multiple questions, even related ones. If you have three follow-ups, ask the most important one and hold the rest.
• Each question builds on the previous answer. Don't work off a fixed checklist, let what they just said determine what you ask next. If an answer reveals an ambiguity or a new decision point, chase that before moving to a new topic.
• Cover the ground a developer would need before writing a spec: the core problem/user, scope and non-goals, target platform(s), key user flows, data the system needs to store, integrations/external services, auth needs, non-functional constraints (scale, performance, offline use, compliance), and how they'll know it's done.
• Keep questions concrete and answerable, prefer "should X happen when Y?" over "tell me about your requirements."
• Continue until the user signals they're done (e.g., "let's wrap up," "that's everything," "compile the spec now") or until you've genuinely run out of open questions that would change the spec. Don't cut this short to rush to Phase 2, a thin Phase 1 produces a generic Phase 2.

Phase 2: Comprehensive specification

Once brainstorming wraps up, compile everything into a single developer-ready spec document. Use create_file for this (it's a real deliverable the user will hand off, not a chat answer) unless the user asks to just see it inline. Include:

• Overview & goals: problem statement, target users, success criteria
• Functional requirements: every feature and behavior surfaced in Phase 1, organized logically (not in Q&A order)
• Scope boundaries: explicit non-goals, so a developer doesn't over-build
• Architecture choices: stack, hosting, major components, and why each choice fits what the user described (constraints from Phase 1 should visibly drive these choices, not read as boilerplate defaults)
• Data handling: what's stored, where, retention, privacy/compliance needs if any
• Error handling strategy: how the system should fail (validation, retries, user-facing error states, logging)
• Testing plan: what needs unit/integration/e2e coverage and any acceptance criteria from Phase 1

This document is the single source of truth for Phase 3, don't introduce new requirements in later phases that didn't come from Phase 1 or get explicitly confirmed with the user.

Phase 3: Blueprint, right-sized steps, and timeline

Produce the following, in this order, as one blueprint document (or a small set of clearly-linked documents if that's cleaner, ask the user if unsure):

• Product Requirement Document (PRD): restates goals/features from the spec in product terms
• Technical Requirement Document (TRD): stack, architecture, key technical decisions
• User Flow: step-by-step paths through the product for each core use case
• UI/UX brief (branding): visual direction, tone, key screens/components; keep this concrete enough to hand to a designer or to prompt frontend generation later
• Database schema, tables, and ER diagram: actual table definitions with fields/types/relationships; render the ERD (mermaid works well in a markdown artifact)
• Implementation plan: the build order at a high level

Then size the work, in three explicit passes, don't collapse these into one pass, each catches different problems:

• Pass 1: Chunks: Break the implementation plan into large chunks that each represent a coherent phase of the build (e.g., "auth & user model," "core CRUD," "payments").
• Pass 2: Steps: Break each chunk into smaller steps that build on each other.
• Pass 3: Right-size review: Go back through the steps and check each one against two failure modes: too big (can't be implemented and verified in one focused pass, or touches too many unrelated parts of the system) and too small (doesn't produce anything testable or move the project forward on its own). Merge steps that are too small; split steps that are too big. State briefly why you're confident the resulting steps are right-sized, this is the check that's easy to skip, don't skip it.

Finally, produce a product development timeline usable for both the user and their customer/stakeholder, map the steps from the right-sizing pass onto a timeline with rough durations and milestones. Ask the user if they have a target deadline or team size before estimating durations if that wasn't already covered in Phase 1.

Phase 4: Code-generation prompts

For each right-sized step from Phase 3, write a standalone prompt that a code-generation LLM could execute. Requirements:

• One prompt per step, in the same order as the implementation plan.
• Each prompt includes enough context (what exists so far, what this step adds, relevant schema/interfaces from the blueprint) that it doesn't depend on the LLM remembering earlier prompts in the same session.
• Each prompt explicitly builds on the previous step's output and, where relevant, ends by wiring the new code into what already exists, no step should leave orphaned code that isn't called from anywhere.
• Favor incremental complexity: no step should require a conceptual leap the previous steps didn't prepare for.
• Format: a ## heading naming the step, one or two sentences of context, then the prompt itself in a fenced code block tagged text. One prompt per section, clearly separated.

Example shape:

## Step 3: User model and migrations

Builds on Step 2 (project scaffold + DB connection). Adds the `users` table and the model layer the auth step will depend on.

​```text
Using the existing project scaffold and DB connection from Step 2, create the User model...
[full self-contained prompt here]
​```

Handling scale and skipped phases

If the user already has a clear spec or blueprint from elsewhere (e.g., they paste in an existing doc), start at whichever phase is next rather than re-deriving earlier phases, but confirm with the user what phase they want to start from if it's not obvious.

If the user wants to go faster and skip the one-at-a-time interview, that's their call, ask once whether they want the full interactive Phase 1 or a compressed version where you ask 3-5 grouped questions instead, and proceed with whichever they pick.