Start here with spec-first development

Write a spec when a change can fail in more than one reasonable way. That usually means the work touches customer data, money, permissions, public API behavior, migrations, background jobs, release flags, or AI-generated code. A short copy change can use a checklist. A refund workflow, schema migration, partner endpoint, notification preference model, or queue consumer deserves a written decision path before implementation starts.

The fastest test is simple: if a reviewer could approve the pull request while still disagreeing with the intended behavior, write the spec first. The spec does not need to predict the implementation. It should name the behavior, the boundaries, the owner, and the evidence that will prove the change is safe enough to ship.

A refund workflow is a good first practice case because the failure modes are concrete. A vague ticket says, "Allow users to refund orders." A reviewable spec decides the refund window, duplicate request behavior, provider timeout state, support override, event emission, audit log, and the rollout signal that should stop the release.

The spec-first version stays compact. It might say: refunds are allowed for captured charges within 90 days; repeated requests with the same idempotency key return the same refund id; provider timeouts move the refund to pending confirmation; and rollout stops if duplicate refund attempts exceed the threshold for 15 minutes. That is enough for engineering, QA, support, and AI coding tools to work from the same boundary.

# Refund workflow acceptance slice

Given a captured charge less than 90 days old
When a refund request arrives with a new idempotency key
Then create one refund record, emit one refund_requested event,
and write an audit entry with actor, charge_id, refund_id, and reason.

Given the same request is replayed with the same idempotency key
When the service receives it again
Then return the existing refund_id and do not emit another event.

When you use an AI coding tool, paste the spec before asking for code. Make the boundaries explicit enough that the model can be judged against them. The prompt should say which files are allowed, which behavior is out of scope, which tests count as evidence, and what the model should do if the spec is ambiguous.

Use the spec below as the source of truth.

Rules:
- Do not add behavior outside the non-goals.
- Only modify the files listed under Allowed files.
- If a requirement is ambiguous, ask before implementing.
- Add tests for every acceptance criterion.
- Return a short evidence summary with changed files and test commands.

Spec:
[paste reviewed spec here]