Spec-first examples you can actually reuse

Use these case studies to see how a loose request becomes a small working packet: spec.md, tasks, acceptance criteria, and test evidence before AI coding starts.

BeforeWeak ticket or prompt
AfterReviewable spec packet
UseCopy into issues and PRs

How to read these examples

Start with the weak request

The before state is intentionally rough. It shows the kind of prompt that often produces a broad AI-generated diff: a goal is implied, constraints are missing, and reviewers have no objective way to reject extra behavior.

Look for the boundary

The useful move is not nicer wording. It is the explicit boundary: non-goals, affected files or systems, compatibility constraints, and the behavior that must not change while the feature is implemented.

Check the evidence

A spec packet is only strong when the acceptance criteria lead to tests, screenshots, fixtures, logs, or rollout signals. The examples show what proof reviewers should ask for before merge.

Featured case studies

Checkout coupon code

A money-touching checkout request becomes a bounded spec with validation states, total calculation, implementation tasks, and rollback evidence.

Weak request:
Add coupon codes to checkout.
Make sure invalid codes do not break payment.

Spec boundary:
- one coupon before payment
- no admin UI
- no totals refactor
Open the coupon case

API error taxonomy

An API error cleanup request becomes a stable contract with compatibility notes, SDK fixtures, OpenAPI examples, and migration evidence.

Weak request:
Improve API errors.
Make them easier for clients to handle.

Spec boundary:
- envelope only
- additive response change
- old SDKs still parse
Open the API error case

Notification preference migration

A settings request becomes a migration packet with opt-out preservation, duplicate-send prevention, and worker-level delivery evidence.

Weak request:
Add notification preferences.
Make sure we do not spam people.

Spec boundary:
- email and push only
- preserve existing opt-outs
- prove no duplicate sends
Open the notification case

Database schema change

A vague account status column request becomes an expand/backfill/switch migration plan with query evidence and rollback boundaries.

Weak request:
Add account_status to accounts.
Make sure reports still work.

Spec boundary:
- nullable expand first
- parity check before switch
- cleanup in a later release
Open the database case

AI PR scope drift

A broad AI-generated pull request becomes a bounded review packet with allowed files, non-goals, diff mapping, and merge evidence.

Weak request:
Fix the settings bug with AI.
Clean up anything related.

Spec boundary:
- allowed paths only
- no billing or auth changes
- changed files map to tasks
Open the AI PR case

Large report export

A CSV export request becomes an async job spec with permissions, filter snapshots, file expiry, queue metrics, and failure handling.

Weak request:
Add CSV export to reports.
Email the file when ready.

Spec boundary:
- async job for large accounts
- same filters as the report
- download expires safely
Open the export case

What makes an example worth indexing

These are not decorative samples. Each example has to teach a reusable decision: how to narrow scope, how to name a failure mode, how to turn acceptance into evidence, or how to keep an AI coding tool from inventing product behavior. If an example only says "write better requirements", it does not belong here.

The library is intentionally smaller than the blog archive. A few complete, reusable cases are more valuable than dozens of shallow variations. New examples are added when they introduce a distinct pattern such as money-touching checkout logic, public API compatibility, migration safety, long-running background work, or notification preference drift.

Checkout and billing

Copy rollback signals, total calculation tests, and invalid-state criteria. Do not copy business rules that only make sense for one product.

API contracts

Copy error envelopes, compatibility notes, SDK fixtures, and OpenAPI examples. Do not rename fields without a migration window.

Vague-ticket rewrites

Copy the before/after structure and evidence checklist. Do not copy every task when your architecture is different.

AI PR review

Copy allowed-path rules, non-goals, and changed-file maps when AI-generated diffs keep expanding beyond the original ticket.

Background jobs

Copy state machines, permission checks, and queue evidence when a user action finishes asynchronously.

Choose the right case

Start with the case that matches the risk in your ticket. The domain does not have to match perfectly; the reusable part is the boundary, evidence, and review move.

Money or totals

Use the checkout coupon case when a bug can change price, payment, refund, or order state.

Public response shape

Use the API error case when clients, SDKs, docs, or generated code depend on a stable contract.

AI-generated PR review

Use the AI PR drift case when a coding assistant changes files or behavior outside the original request.

Long-running work

Use the large export case when work runs in a background job and needs permissions, state, and operational evidence.

Example maintenance rubric

Every indexed example has to survive the same review rubric. First, the page must contain a concrete before state, not only advice about writing better requirements. Second, the after state must be copyable into a real engineering workflow: a spec, a task list, acceptance criteria, or an evidence checklist. Third, the example must explain why the rewrite reduces rework instead of merely sounding more professional.

That rubric matters for readers and for search quality. A page with a few cards and a CTA can look polished while still being thin. A useful example page should help a developer make a decision in the next five minutes: whether to narrow scope, add a compatibility note, split an AI coding task, or ask for a specific test before merge. If the example does not support that kind of action, it should be expanded, merged into a stronger page, or removed from indexing.

Originality

The example must add a specific scenario, failure mode, or artifact that is not already covered by a stronger page.

Reuse

The reader should be able to copy at least one section into an issue, pull request, repo spec, or review checklist.

Evidence

The page should name the proof required before merge, because that is where most vague AI coding prompts fail.

Common mistakes these examples avoid

Use this section as a quick self-check before publishing a new case. The page should show the messy input, the corrected packet, and the evidence bar; otherwise it is only a teaser for a stronger resource.

Only showing the polished answer

Without the weak original request, readers cannot see which ambiguity was removed. The before state is part of the lesson.

Leaving evidence until the end

Evidence should be designed with the spec. Adding it after implementation turns review into a summary instead of a verification step.

Copying domain rules blindly

The reusable part is the shape of the packet. Product-specific rules should be rewritten for the reader's own systems, risks, and release process.

Quick before/after examples

Notification preferences

Turn a broad settings request into migration risks, preference states, and duplicate-send evidence.

Open full case

Database schema change

Turn "add a status column" into phased migration tasks, parity checks, and rollback boundaries.

Open full case

More compact rewrites

Compare loose tickets against spec packet versions for scope, tasks, acceptance, and evidence.

Browse quick examples

AI PR drift review

Turn "fix it with AI" into allowed paths, non-goals, and a changed-file evidence map.

Open full case

Large report export

Turn a CSV button request into an async job, permission checks, and queue evidence.

Open full case

Start from your own vague request

Paste a messy requirement into the AI Coding Spec Packet generator and turn it into four reviewable Markdown files.

Generate a spec packet Open feature spec template

Editorial note

Examples are selected for practical reuse: each case must show a real before/after move, a spec boundary, and review evidence.