Build (Phase 4)

Implement from approved plans and specs with surgical edits and work-item traceability.

Prerequisite

.claude/sdlc/gates/design-<task-slug>.md must exist and be signed. (For fixes under the /fix --fast path, a compressed gate is acceptable — see commands/fix-fast.md.)

Step 1 — Validate the work item

Before any Edit/Write, confirm based on the plan's classification:

• New build → the code change must reference at least one REQ-<n> ID from .claude/sdlc/requirements/<task-slug>.md. If none, halt and ask.
• Fix → the change must reference an issue ticket. Detect the ticket system from .claude/sdlc/env.json:
  • GitHub/GitLab/Bitbucket Issues → require an issue URL or number
  • Jira/Linear (via MCP) → require an issue key
  • No ticket system detected → require a local ticket file under .claude/sdlc/tickets/ using templates/ticket.md
• Change request → the change must reference a CR with a sign-off artifact under .claude/sdlc/sign-offs/CR-<n>.md. No sign-off → halt.

The work-item-validation.sh hook enforces this at the tool level.

Step 2 — Implement with surgical-edit discipline

Delegate the how of editing to the surgical-edit skill, which enforces:

• Smallest diff that satisfies the plan
• Only files in the plan's in-scope list
• Only functions in the plan's in-scope list (no adjacent-function edits)
• No speculative refactoring, renaming, or "while I'm here" cleanups
• Unrelated bugs → .claude/sdlc/followups/<task-slug>.md, not fixed in this change

The diff-scope-check.sh and adjacent-function-detector.sh hooks enforce these post-write.

Step 3 — Validate against specs

After writing, run a conformance pass:

• Code shape matches the tech spec (API signatures, error modes, side effects)
• NFRs addressed (or explicitly deferred with justification)
• Security controls from the security architecture are in place for the modified surface

If the build touched a frontend surface, run the UX conformance checklist against the rendered UI (screenshots live under .claude/sdlc/test/ux/).

Step 4 — Unit tests for MODIFIED CODE ONLY

Extract the list of functions modified from git diff. For each modified function:

• Add or update its unit test(s) under .claude/sdlc/test-scripts/ (mirroring source tree)
• Tests reference the test cases from Design and, through them, the REQ IDs

Do not rewrite tests for unmodified functions. The modified-code-test-gate.sh hook verifies the test-to-function mapping.

Step 5 — Deployment scripts and pipeline

If the change requires:

• New env var → update the deployment script and the pipeline config in the same commit
• New secret → update the secrets management doc and the pipeline; never commit the secret
• New service, queue, bucket → update infra-as-code
• New test gate → update the pipeline

Deployment updates ride with the code change. Never defer.

Human gate

Summarize: files modified, functions modified, tests added/updated, pipeline changes, UX conformance status. Sign-off goes to .claude/sdlc/gates/build-<task-slug>.md.

References

• skills/surgical-edit/SKILL.md
• skills/minimal-code/SKILL.md
• skills/security-review/SKILL.md
• hooks/work-item-validation.sh, hooks/diff-scope-check.sh, hooks/adjacent-function-detector.sh, hooks/modified-code-test-gate.sh
• templates/ticket.md, templates/change-request.md, templates/sign-off.md

Next step hint

After writing the gate file, pipe the next_suggestions conditions to skills/_shared/next-hint.sh and print any output:

printf '%s\n' \
  'build_gate_signed|run /test to execute tests and record defects' \
  'pending_signoff_for_current_user|write your sign-off at sign-offs/<REQ-ID>-<role>.md, then /test when all roles are covered' \
  | bash skills/_shared/next-hint.sh

Print any output verbatim. If the script outputs nothing, add nothing.