Why rewrite vague tickets before AI coding?

AI coding tools execute the ambiguity they receive. A short spec packet makes scope, acceptance, risks, and evidence visible before implementation starts.

How much detail is enough?

Enough for a reviewer to reject scope creep and for QA to create tests without interviewing the author. Most small features need one or two pages, not a full PRD.

From vague requirement to executable spec

These examples show the exact move Spec Coding is built around: take a weak AI coding prompt and turn it into files that reviewers, testers, and agents can follow.

BeforeAmbiguous ticket or prompt

AfterSpec, tasks, acceptance, evidence

UseCopy into issues, PRs, or repos

Example 1: notification preferences

Vague ticket

Make notification settings clearer.
Users should know what they are subscribed to.

Spec packet version

spec.md
- Goal: show email, in-app, and push preferences per event.
- Non-goal: no new notification provider.
- Risk: duplicate sends during migration.

acceptance-criteria.md
- Given an existing user with email disabled
  When preferences are migrated
  Then email remains disabled for every event.

test-evidence.md
- migration dry run
- old mobile client screenshot
- duplicate notification regression test

Example 2: API error handling

Vague ticket

Improve API errors.
Make them easier for clients to handle.

Spec packet version

spec.md
- Goal: standardize error code, message, trace_id, and retryable.
- Non-goal: no endpoint behavior changes.
- Constraint: old SDKs must parse the response.

acceptance-criteria.md
- Given a validation failure
  When the API returns 422
  Then response includes code, message, field_errors, trace_id.

test-evidence.md
- contract test for 400/401/409/422
- SDK compatibility fixture
- release note for changed examples

Example 3: report export

Vague ticket

Add CSV export to reports.
Should work for large accounts.

Spec packet version

spec.md
- Goal: async CSV export for reports up to 1M rows.
- Non-goal: no PDF export.
- Risk: long-running jobs and stale filters.

tasks.md
- persist export request with filters
- run worker with retry and idempotency key
- notify user when file is ready

test-evidence.md
- 1M row load test
- failed worker retry test
- expired download link check

Turn your own ticket into a packet

Use the generator when a request is clear enough to discuss, but still too vague to hand directly to an AI coding tool.

Generate a spec packet