Spec Guides

What you get from each guide

Every guide follows the same structure: a one-paragraph summary of why the topic matters, a short reusable example you can copy directly into your spec or ticket, and deeper sections covering edge cases, role-specific questions, and decision rules. The goal is a page you can open at the start of a sprint, scan in five minutes, and leave with a concrete artifact.

Guides are intentionally shorter than blog articles. Where a blog post explains the reasoning behind a practice in depth, a guide gives you the checklist or template first — with enough context to apply it without back-reading theory.

How to use these guides with your team

The most effective way to use these guides is to assign one per role before a spec review meeting. The PM reads the PRD-to-spec guide and scope non-goals checklist. The tech lead reads the edge case and API contract checklists. QA reads the acceptance criteria examples and spec review checklist. Each person arrives with specific questions rather than reviewing the same surface.

If you have less than 30 minutes before a review, start with the spec review checklist — it is the single fastest way to surface the gaps that cause the most rework: missing rollback steps, untestable acceptance criteria, and unconfirmed dependencies.

When specs need a guide vs when they need a template

Use a guide when you are trying to answer a question: "what should a good acceptance criterion look like?" or "which edge cases am I most likely to miss?" Use a template when you are ready to write: you know what you want to capture and need a structured format to fill in.

Most spec work starts with a guide — to calibrate what good looks like — then moves to a template to produce the actual artifact. The guides on this page link to their corresponding templates so you can move between the two without losing context.

Which guide to start with

If your team skips spec reviews or has frequent rework from misunderstood requirements: start with the Spec Review Checklist. It surfaces the most common gaps in the shortest time.

If your team writes specs but QA frequently finds issues at test time: start with Acceptance Criteria Examples — the pattern most teams get wrong is writing criteria that are technically true but not testable without interpretation.

If you use AI coding tools and find the output frequently drifts from requirements: start with the AI Coding Prompt Template.