Skip to content

SOP-057 — Peer code review (Staff Engineer)

Guide

<!-- last-reviewed: 2026-06-01 · owner: Engineering (Staff Engineer) -->

SOP-057 — Peer code review (Staff Engineer)

SOP · owner: Engineering (Staff Engineer). Layer: SOP/Runbook (docs/canon.md). The Staff Engineer’s review of code produced within the Engineering unit, before it reaches the Director’s first-line review (SOP-054). Conventions live in CLAUDE.md (linked, not restated).

Interface Contract

  • Inputs: peer product-code diff ← from <Platform Engineer / Staff Engineer / AI Engineer> · trigger: review requested
  • Outputs: peer-reviewed diff → to Engineering Director · trigger: review requested
  • Handoff trigger (in): a unit member’s product-code change is build-green and ready for a peer read
  • Handoff trigger (out): the diff passes peer review (or returns with rationale) and is escalated to the Director’s review
  • Definition of Done before handoff:
    • [ ] Diff read in full against CLAUDE.md Coding Conventions + CONTRIBUTING.md
    • [ ] Correctness, missing tests, intent-obscuring naming called out with rationale
    • [ ] Scope creep into Operations / Data & Analytics / AI Systems territory flagged
    • [ ] Author confirmed npm run build green before review
    • [ ] Learnings captured to docs/knowledge/ if the review surfaced one

review requested is the same registry phrase on both legs: the peer hand-in and the escalation to the Director (SOP-054). Peer review is a within-unit quality gate that precedes the Director’s first-line review — it does not replace it (README.md R7/R11).

Purpose

Catch correctness bugs, missing tests, and convention drift early — at peer altitude — so the Director’s review and the release stay fast and the codebase quality stays even across members (R7).

When to use

When a unit member hands a build-green diff for a peer read before the Director’s review. If the build is not green, stop — the author fixes it first.

Flow

flowchart LR
  A["review requested<br/>(peer diff)"] --> B["Read full diff<br/>vs CLAUDE.md"]
  B --> C{"Correct? tested?<br/>in scope?"}
  C -->|no| D["Return with<br/>rationale"]
  C -->|yes| E["escalate:<br/>review requested → Director"]
  D --> A
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class A,B,D,E s
  class C d

Text fallback: a build-green peer diff arrives (review requested) → read it in full against CLAUDE.md → if correct, tested, and in scope, escalate to the Director’s review (review requested, SOP-054); otherwise return it with specific rationale.

Steps

  1. Confirm the build is green (author reports npm run build output). No evidence → return.
  2. Read the full diff against CLAUDE.md Coding Conventions + CONTRIBUTING.md.
  3. Call out, with rationale: correctness bugs, missing tests, naming that obscures intent, and any scope creep (process changes → Process Engineer; schema/scoring → Data & Analytics; prompts/models → AI Systems).
  4. Return or escalate. Return with rationale, or escalate to the Director’s first-line review (SOP-054) via review requested.
  5. Capture learnings to docs/knowledge/ if the review surfaced one.

Roles / approvers

Run by the Staff Engineer (peer review). The Engineering Director holds the first-line review authority (SOP-054); peer review precedes, not replaces it.

Guardrails

  • Peer review is not the sign-off proof — the Director’s review (SOP-054) and the Q&R sample are (README.md R11).
  • Flag, don’t fix, out-of-scope creep — name the edge and the owner.
  • Do not restate CLAUDE.md — link to it.

Job aid: (N/A — peer review reuses the same convention checklist as SOP-054; no separate cheat-sheet adds value, GR-4). See also: docs/units/engineering/manuals/staff-engineer.md · SOP-056 · SOP-054 · CLAUDE.md · docs/handoff-triggers.md.