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

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.