Skip to content

SOP-056 — Build a feature / fix a bug (Staff Engineer)

Guide

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

SOP-056 — Build a feature / fix a bug (Staff Engineer)

SOP · owner: Engineering (Staff Engineer). Layer: SOP/Runbook (docs/canon.md). The implementation loop for the intranet/ frontend and the sync-content.mjs pipeline. Conventions live in CLAUDE.md (linked, not restated).

Interface Contract

  • Inputs: sprint task / bug report ← from Project Manager · trigger: briefing posted
  • Inputs: technical design / architecture decision ← from <Engineering Director> · trigger: review passed
  • Inputs: compliance/license requirements ← from <Legal Director> · trigger: requirements issued
  • Outputs: build-green code change → to Engineering Director · trigger: review requested
  • Outputs: authored spec / post-mortem → to Archivist · trigger: artifact approved
  • Handoff trigger (in): a sprint task or bug is assigned and its acceptance criteria are clear
  • Handoff trigger (out): the change builds green and is ready for the Director’s review (SOP-054)
  • Definition of Done before handoff:
    • [ ] Acceptance criteria confirmed (or ambiguity surfaced to the Engineering Director)
    • [ ] Smallest buildable increment; existing patterns reused, no new abstraction where one fits
    • [ ] cd intranet && npm run build green (~50 pages, [sync] …) — real output reported
    • [ ] Bug fixes traced to root cause; cause noted in a code comment or PR note
    • [ ] Test added/updated, or the test gap noted explicitly as a follow-up (no framework yet)
    • [ ] Learnings captured to docs/knowledge/ if the change surfaced one

Trigger phrases drawn from docs/handoff-triggers.md. The briefing posted in-edge (task assignment from the PM) and the review passed design hand-down from the Director are absorbed as fan-out / intra-unit edges; review requested is the first-line review hand-up to the Director (SOP-054), matched by the Q&R fan-in sink for independent assurance (interface-contract-spec.md §3.1 R1).

Purpose

Translate a sprint task or bug into working, build-green code with craft — without gold-plating, without going dark, and without silently shipping untestable code.

When to use

When a sprint task or bug is assigned with clear (or clarifiable) acceptance criteria. If the task implies an unmade architecture decision, stop — surface it to the Engineering Director first.

Flow

flowchart LR
  A["task / bug"] --> B{"arch decision<br/>needed?"}
  B -->|yes| ED["surface to<br/>Engineering Director"]
  B -->|no| C["implement<br/>smallest increment"]
  C --> D{"npm run build<br/>green?"}
  D -->|no| C
  D -->|yes| E["review requested<br/>(SOP-054)"]
  ED --> C
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class A,ED,C,E s
  class B,D d

Text fallback: a task/bug arrives → if it implies an unmade architecture decision, surface it to the Director; otherwise implement the smallest buildable increment → npm run build until green → hand up for review (review requested, SOP-054).

Steps

  1. Confirm acceptance criteria. If ambiguous or architecture-touching, stop and surface to the Engineering Director before writing code.
  2. Read before writing. Read the file + dependencies; match conventions. Mind the named footguns: never run astro build bare (run npm run build/dev, which sync first); import.meta.glob stays inside getStaticPaths; watch for slug collisions in sync-content.mjs (slugOf, line 46).
  3. Implement incrementally. Smallest change satisfying the criteria; each increment leaves the codebase buildable.
  4. For bugs: trace to root cause before writing the fix; note the cause in a comment.
  5. Run the build. cd intranet && npm run build; report real output. Fix red before moving on.
  6. Test. Add/update a test exercising the behavior. If no framework exists, note the gap explicitly as a follow-up — do not ship untestable code silently.
  7. Hand up for review (review requested) and hand any authored doc to the Archivist (artifact approved). Capture learnings to docs/knowledge/.

Roles / approvers

Run by the Staff Engineer. Review/approval by the Engineering Director (SOP-054). Out-of-scope discoveries flag to the Project Manager as new tasks.

Guardrails

  • No architecture decisions (new frameworks, dependencies, structural changes) without Engineering Director sign-off — surface and wait.
  • No pipeline edits (.github/workflows/, .claude/hooks/, vercel-ignore.sh) — propose to the Process Engineer.
  • No schema-contract or scoring-logic changes — that’s Data & Analytics’.
  • Personal information is PA-only — never read or publish it.
  • Do not restate CLAUDE.md — link to it.

Job aid: docs/units/engineering/job-aids/JA-056-local-dev-build-cycle.md. See also: docs/units/engineering/manuals/staff-engineer.md · SOP-057 (code review) · SOP-054 · CLAUDE.md · docs/handoff-triggers.md.