← Code review and governance guides

How to create a SpecDD review checklist

How-To Code review and governance Beginner 1141005HOWTO-1141005

HOWTO-1141005Code review and governanceBeginner

This guide shows you how to create a practical spec-driven development review checklist for pull requests, spec-only changes, and agent-generated work.

A useful checklist keeps review focused on the contracts that matter: authority, behavior, boundaries, tasks, and evidence. It should not make every small edit feel like architecture review.

Short answer

Create a checklist that asks whether the correct specs were used, changed files are authorized, Must behavior is satisfied, Must not and Forbids still hold, tasks and Done when match reality, and verification matches risk. Keep it short enough that reviewers actually use it.

When to use this guide

Use this guide when:

What you will build

By the end of this guide, you will have:

Steps

1. Choose what the checklist reviews

Decide whether the checklist is for:

You can use one core checklist and add small risk-specific sections. Avoid separate long checklists for every workflow unless your team really needs them.

2. Check spec chain and authority

Start with authority because it answers whether the change belongs in the pull request.

Checklist items:

This section catches most wrong-file changes early.

3. Check behavior and boundaries

Checklist items:

For a low-risk documentation or wording change, this section may take seconds. For behavior changes, it is the center of the review.

4. Check tasks and completion

Checklist items:

Task markers are small, but they shape future work. Review them like other contract changes.

5. Check verification

Checklist items:

Verification should match risk. Not every spec edit needs a full test suite, but every meaningful contract change needs some reviewable evidence.

6. Scale by risk

Use a lighter path for:

Use stronger review for:

The checklist should make high-risk changes visible without slowing down small safe edits.

7. Keep the checklist short

Prefer a checklist reviewers can scan:

## SpecDD review

- [ ] Governing spec or task is named.
- [ ] Changed files are inside `Can modify` or `Owns`.
- [ ] `Can read` and `References` stayed read-only.
- [ ] `Must` behavior is satisfied or preserved.
- [ ] `Must not` and `Forbids` still hold.
- [ ] Spec updates are included when durable behavior changed.
- [ ] Task status and `Done when` match the evidence.
- [ ] Checks were run or skipped with explanation.

Add high-risk prompts only when they apply.

High-risk add-on

For boundary or authority changes, add:

## High-risk SpecDD review

- [ ] Why is authority changing?
- [ ] Which parent or sibling specs are affected?
- [ ] Does this weaken a previous `Must not` or `Forbids`?
- [ ] Are rejected approaches still blocked where needed?
- [ ] Do owners of affected areas agree?
- [ ] What checks prove the new boundary is safe?

Use this add-on for the highest-risk changes, not every pull request.

Common mistakes

How to verify the result

The checklist is working when:

← Code review and governance guides