Code Quality & Review Standards

Trunk-based development with protected main branches, mandatory PR reviews, code quality standards, and version control best practices.

Milestone: Foundation

foundational

CFR

Job to be done: When our code changes suffer from inconsistent reviews and architectural drift, I want to adopt trunk-based development with clear ownership and standards, so I can ship with confidence and reduce the time wasted on merge conflicts.

For engineers

You will set up trunk-based development with protected main branches, implement PR checklists and code ownership boundaries, add automated formatting/linting checks, and establish an ADR process for major decisions. Work through branch protection rules, CI enforcement, and review SLAs to ship changes with consistent quality.

What you’ll implement

These are the roadmap epic features, organized as a starter backlog.

Git Workflow Standard

PR Review Checklist

PR Review Turnaround SLA

Conventional Commit Messages

Pair/Mob Programming

Code Readability Standards

Execution guide

Practical guidance aligned to the Execution Kit Definition of Done.

Outcome

Teams ship changes with predictable review quality, consistent branching/PR hygiene, and a shared definition of what ‘good engineering’ looks like.

Before to After Transformation

× BEFOREChaotic branching

Long-lived feature branches, painful merges, inconsistent reviews, 'works on my machine' syndrome

# Typical chaos:
git checkout -b feature/big-rewrite
# ... 3 weeks later ...
git merge main  # 50 conflicts
# No required reviews, push straight to main

AFTERTrunk-based flow

Short-lived branches, fast PRs, automated checks, consistent quality across all teams

# Trunk-based with protection:
git checkout -b feat/small-change
# PR created, auto-assigned reviewers
# ✓ CI passes (build, test, lint)
# ✓ 1 approval required
# ✓ Merged to main within hours

# DORA improvements:
# - Deployment frequency: weekly to daily
# - Lead time: 7 days to 2 days

Symptoms

Long-lived branches and painful merges

Inconsistent code review quality

Frequent regressions and ‘works on my machine’

Architecture drift and undocumented decisions

Prerequisites

A protected default branch (e.g., main)

A PR review workflow in place

Basic CI that runs on PRs

Implementation steps

Week 1

Adopt trunk-based development policy (branching strategy and max branch age)
Introduce a PR checklist and review expectations
Add a lightweight engineering standards README (per repo or org)

Week 2

Add ADR process (when to write, where to store, review cadence)
Define code ownership boundaries and reviewers
Add automation for formatting/linting (fail PR on violations)

Week 3

Reduce PR size via work slicing guidance
Introduce review SLAs (p50 < 24h) and track cycle time
Run a retro to iterate the policy (what’s too strict / too loose)

Definition of Done

Trunk-based workflow documented and adopted
PR checklist enforced and used consistently
CI checks required before merge
ADR template available and used for major decisions
Practice integrated into team workflow

Metrics

Leading Indicators

PR cycle time (p50/p95)
Average PR size (lines changed)
% PRs passing CI on first try

Lagging Indicators

Change failure rate
Lead time for changes

Failure modes

Policy is written but not enforced (no branch protection / no checks)

Review becomes a bottleneck (no SLAs, unclear ownership)

Trunk-based adopted without adequate test safety net

Ownership

Engineering leadership

Set expectations and protect the time budget for reviews
Ensure incentives reward quality outcomes

Platform/DevOps

Configure branch protection and required checks
Provide templates (PR checklist, ADR)

Teams

Follow the workflow and continuously improve it
Keep ADRs and standards current

What good looks like (by org scale)

Small Teams

Branch protection + required CI checks
PRs reviewed within 1 business day

Medium Orgs

Clear code ownership
ADRs for major decisions
PR size norms + work slicing

Enterprise

Org-wide policy with limited exceptions
Audit-friendly review evidence
Measured PR cycle time by org/portfolio

References

Trunk Based Development

DORA: Accelerate (Forsgren/Humble/Kim)

Resources

Templates and related materials for this kit.

Templates

Copy/paste artifacts that support this kit.

Architecture Decision Record (ADR)

A short ADR template for recording decisions and keeping architecture aligned over time.

Definition of Done (DoD)

A ready-to-use DoD checklist that bakes in quality, security, and operability.

Secure SDLC Checklist (Lightweight)

A simple, repeatable checklist for security-by-default in planning, coding, and release.

Service Onboarding Checklist (Golden Path)

A checklist for onboarding a new service into the platform: ownership, CI/CD, observability, and security.

Service README

A lightweight README template for services (ownership, deploy, runbooks, SLOs, dependencies).

Related capabilities

Capabilities tracked under this epic in the roadmap.

Git Workflow Standard
>= 95% of code changes follow trunk-based development or GitHub flow (feature branches < 2 days old).
PR Review Checklist
>= 90% of PRs have checklist completed before merge (tests, docs, security, performance).
PR Review Turnaround SLA
>= 80% of PRs receive first review within 4 business hours.
Conventional Commit Messages
>= 85% of commits follow conventional commit format (type(scope): description).
Pair/Mob Programming
>= 40% of complex features (>= 5 story points) developed using pair or mob programming.
Code Readability Standards
>= 70% of modules have README with setup, usage, and architecture notes. Code review checks readability.

Related kits

Other kits in the same milestone or with similar DORA impact.

Testing Strategy & Quality Gates

Foundation

CFR

Backlog Quality & Planning Enablement

Foundation

CI/CD & Build Automation

Foundation

Observability & Monitoring Foundations

Foundation

MTTR

CFR

Before to After Transformation

× BEFOREChaotic branching

Long-lived feature branches, painful merges, inconsistent reviews, 'works on my machine' syndrome

# Typical chaos:
git checkout -b feature/big-rewrite
# ... 3 weeks later ...
git merge main  # 50 conflicts
# No required reviews, push straight to main

AFTERTrunk-based flow

Short-lived branches, fast PRs, automated checks, consistent quality across all teams

# Trunk-based with protection:
git checkout -b feat/small-change
# PR created, auto-assigned reviewers
# ✓ CI passes (build, test, lint)
# ✓ 1 approval required
# ✓ Merged to main within hours

# DORA improvements:
# - Deployment frequency: weekly to daily
# - Lead time: 7 days to 2 days

Implementation steps

Week 1

Adopt trunk-based development policy (branching strategy and max branch age)
Introduce a PR checklist and review expectations
Add a lightweight engineering standards README (per repo or org)

Week 2

Add ADR process (when to write, where to store, review cadence)
Define code ownership boundaries and reviewers
Add automation for formatting/linting (fail PR on violations)

Week 3

Reduce PR size via work slicing guidance
Introduce review SLAs (p50 < 24h) and track cycle time
Run a retro to iterate the policy (what’s too strict / too loose)

Ownership

Engineering leadership

Set expectations and protect the time budget for reviews
Ensure incentives reward quality outcomes

Platform/DevOps

Configure branch protection and required checks
Provide templates (PR checklist, ADR)

Teams

Follow the workflow and continuously improve it
Keep ADRs and standards current