definition-of-done

Overview

Per scrum-guide:

"The Definition of Done is a formal description of the state of the Increment when it meets the quality measures required for the product."

"If the Definition of Done for an increment is part of the standards of the organization, all Scrum Teams must follow it as a minimum. If it is not an organizational standard, the Scrum Team must create a Definition of Done appropriate for the product." (scrum-guide)

The DoD is the team's contract with itself. Without it, "done" varies per PM / per developer / per sprint.

When to use

• A new team needs to author its first DoD.
• An existing team's DoD is stale (years old; doesn't reflect current quality bar).
• A retro identified that "done" means different things to different team members.
• An audit / compliance review needs a documented quality bar.

Starter DoD (recommended baseline)

Most teams converge on something like:

# Definition of Done - `<team>`

A story / PR is "Done" only when ALL of the following are true:

1. **Code reviewed** by at least one other engineer; review approval
   recorded.
2. **Tests** for new behavior:
   - Unit test coverage on changed files >=80%.
   - At least one test per acceptance criterion.
3. **Documentation** updated:
   - User-facing changes have updated docs (or "no user-facing
     change" is documented).
   - API changes have updated OpenAPI / Swagger / type definitions.
4. **Acceptance criteria** from the story all pass (manual or
   automated; per AC ID).
5. **Deployed to staging** and smoke test passed (per
   `smoke-suite-gate`).
6. **No new accessibility regressions** (axe / pa11y / Lighthouse
   a11y category green vs main).
7. **Telemetry / observability** wired for new features (per
   `synthetic-monitor-author` in the qa-shift-right plugin).
8. **Security review** for changes that touch auth / payments /
   PII - threat-model entry recorded.
9. **No new tech debt** introduced without an issue logged.
10. **Build green** on the target branch (CI check required).

Customize per team - not all 10 apply to every project.

Per-organization vs per-team

Per scrum-guide:

"If the Definition of Done for an increment is part of the standards of the organization, all Scrum Teams must follow it as a minimum."

If the org has a security review requirement, every team's DoD includes it. The team's DoD can add stricter team-specific lines on top, but can't drop org-wide minimums.

Categorization of DoD lines

The categorization helps when adding lines: "do we have a coverage of the security category?"

Generated per-PR checklist

The DoD becomes a PR template:

<!-- .github/pull_request_template.md -->

## Description

(what changed and why)

## Definition of Done checklist

- [ ] Code reviewed by ≥1 engineer.
- [ ] Unit tests added for new behavior; coverage check passes.
- [ ] Documentation updated (or "no user-facing change" noted below).
- [ ] All AC from the story pass.
- [ ] Deployed to staging; smoke suite green.
- [ ] No new a11y regressions (axe report attached for UI changes).
- [ ] Telemetry / monitoring wired for new features.
- [ ] Security review for auth / payment / PII changes (link to threat model).

## Notes

(any DoD line marked N/A - explain)

A reviewer reads this template + the actual PR state and verifies each line.

DoD evolution

The DoD should evolve with the team's quality bar:

• After an a11y incident → add the a11y line.
• After a security incident → add the threat-model line.
• After production-canary saved a regression → add the canary-passed line.

Don't lower the DoD without explicit retro discussion. Lowering because "we kept failing the gate" usually means the team needs better tooling, not a lower bar.

Review cadence

Auditing adherence

The other half of the lifecycle: a compliance audit of work against the checklist that already exists. The checklist is an input, treated as fixed for the duration of the audit; the output is a per-line verdict backed by artifacts. Authoring is collaborative and can trade a line away; auditing is adversarial and cannot. If a line turns out to be unenforceable, that is a finding to hand back to the authoring conversation, not a licence to skip it.

Two facts from the 2020 Scrum Guide (scrumguides.org/scrum-guide.html) anchor the audit: the team or organization owns the lines (so the audit never invents or edits a line), and a miss has a defined consequence - an item that does not meet the DoD "cannot be released or even presented at the Sprint Review" and returns to the Product Backlog, so "not met" is not advisory. Do not over-attribute: the November 2020 revision made the DoD a formal commitment attached to the Increment (scrumguides.org/revisions.html); the Guide prescribes no checklist content, coverage number, or verdict vocabulary - those are practitioner convention. Many teams also run an entry-side "ready for development" checklist; it is auditable with the same method but has no standing in the Scrum Guide, so declare which stage is being audited before starting ("acceptance criteria" at entry means they exist and are testable; at exit it means covered by tests that ran and passed).

Audit setup

• Pin the checklist revision and the evidence window. Record the checklist file path and commit / date, and what counts as evidence: for a PR, the diff range and the CI runs attached to the head commit; for a release, the commit range in the tag. A green CI run for a different SHA proves nothing about this one.
• Split the checklist into atomic lines. A compound line ("coverage >=80% and one test per AC") is audited as two lines. Do not derive lines from prose - if the checklist is a paragraph, hand it back for restructuring rather than substituting the auditor's reading for the team's intent.
• Handle conditional lines explicitly. "Docs updated (or no user-facing change)" has two satisfying branches; show evidence for whichever branch is claimed. "No files under the UI or API surface changed in the diff" is checkable; a bare assertion of the escape branch is not.
• Scope one audit to one artifact - one PR, one story, or one release candidate.

Line-pattern to evidence mapping

Thresholds come from the team's line, never from a default; if the line names no number ("good test coverage"), it is unverifiable and the finding is that the line is unenforceable as written.

Three states, four evidence standards, one verdict

The three states apply per line and are never averaged - a checklist is not scored out of ten. unverifiable is a real finding: the line names no checkable condition, the convention does not exist, or the artifact was never produced.

Evidence standards: self-attestation is not evidence (a ticked PR-template checkbox is the claim under audit, not proof); a doc claim with no diff is not met; pre-existing failure is not a free pass (a budget already breached on base does not become an acceptable baseline); urgency and size do not waive lines (a faster hotfix bar is a separate written checklist, not an in-flight waiver).

unverifiable never auto-passes - it clears only when a named person supplies the missing evidence, recorded like any other artifact. No checklist means no verdict: inventing a plausible generic one substitutes the auditor's judgment for the team's, which the Scrum Guide assigns to the team or the organization.

Audit report shape

## DoD adherence review - <artifact under audit>

**Stage:** stage-1-entry | stage-2-exit
**Checklist source:** <path> @ <revision>, <N> lines split into <M> audited lines
**Evidence window:** <base>..<head>, CI runs for <sha>
**Verdict:** ACCEPT | REJECT | INCONCLUSIVE
**met: <x>   not met: <y>   unverifiable: <z>**

| # | Checklist line | State | Evidence sought | What was found |
|---|---|---|---|---|
| 1 | ... | met | ... | ... |

Follow with a "Not met" block (required vs actual vs artifact per line), an "Unverifiable" block (searched / blocked by / to resolve), and a one-sentence recommended action tied to the verdict rules. A full stage-2 audit worked end to end is in references/adherence-worked-example.md.

Audit limitations: roughly half of a typical checklist is not machine-checkable (review quality, "no new tech debt") and resolves to unverifiable by construction; presence is not correctness (nothing reads the doc to confirm it describes the change); evidence outside the window is invisible unless recorded; and the verdict is advice, not enforcement - deciding to ship anyway is a human decision worth recording next to the report.

Anti-patterns

Limitations

• Subjective per-team. "What's good enough" varies; the DoD reflects the team's context, not a universal standard.
• Coverage thresholds are arbitrary. "≥80%" is convention; the right number depends on the codebase.
• Some lines are unverifiable automatically ("docs updated" needs human review). The DoD acknowledges these - mark them "unverifiable" rather than auto-passing.

References

• sg - Scrum Guide DoD: "a formal description of the state of the Increment when it meets the quality measures required for the product"; team owns it (or follows org-mandated minimum); items not Done return to the Product Backlog.
• smoke-suite-gate - CI gate that satisfies the "staging deploy + smoke passed" line.