SDD Change Proposal Template

Use this template when a ticket is too risky for a sentence but too early for implementation detail. It captures the behavior, boundaries, owner, and review evidence before the team writes code.

spec.md

# Change Proposal

Owner:
Status: Draft | Review | Approved
Date:

## Problem
- What is broken, missing, or changing?

## Goal
- What user or system behavior must be true after this ships?

## Non-goals
- What is explicitly out of scope for this change?

## Acceptance Criteria
- Given ...
  When ...
  Then ...

## Open Questions
- [ ] ...

## Evidence Required
- Test:
- Log or metric:
- Manual check:
- Rollback signal:

When to use this template

A product request changes behavior across more than one screen or service.
A founder or PM needs engineering to confirm scope before work starts.
An AI coding agent needs a source-of-truth packet before implementation.
A reviewer needs to see non-goals before approving the plan.

What a filled version looks like

The template becomes useful after it carries a real decision, owner, and evidence. This is the level of specificity to aim for.

## Goal
- Refund a captured charge within 90 days without creating duplicate refunds.

## Non-goals
- No new payment provider.
- No bulk refund flow.

## Acceptance Criteria
- Given the same idempotency key is replayed
  When the refund endpoint receives it again
  Then the existing refund_id is returned and no second event is emitted.

Review before implementation

Goal is one behavior outcome, not a task list.
Non-goals remove at least one tempting scope expansion.
Each acceptance criterion can be tested or inspected.
Evidence names the test, log, metric, screenshot, or manual check expected before merge.

Weak vs strong wording

Weak

Allow users to refund orders and make sure duplicate refunds do not happen.

Strong

Captured charges may be refunded for 90 days. Replayed requests with the same idempotency key return the existing refund_id, do not create a second row, and do not emit a second refund_requested event.

FAQ

Is this different from a PRD?

Yes. A PRD explains product intent. This change proposal turns that intent into engineering behavior, acceptance criteria, and evidence.

How long should it be?

Most useful proposals fit on one page. If the change needs architecture trade-offs, link to a design doc instead of expanding this template forever.

When is it ready for implementation?

It is ready when reviewers agree on scope, non-goals, affected systems, and the evidence required before merge.

Related resources

Editorial note

This template is written for spec-driven development workflows. The example is illustrative and should be adapted to your domain.

Author: Daniel Marsh
Editorial policy: How we review and update content

Tip: keep it under /docs/specs/ or /.specs/, then update it in the same pull request as implementation changes. Last updated: May 11, 2026.