Final Code Review

Use this skill after implementation and focused tests are complete, before a human approves a change. It is a final blind-spot review for correctness, maintainability, repository fit, and honest verification. It does not replace a language-specific standard, security specialist, release owner, or the project's own acceptance criteria.

When to Use

• A feature, repair, refactor, migration, or dependency change is ready for pre-merge review.
• A change compiles or passes a narrow test but needs an independent check for structural, operational, or maintainability failures.
• A team needs a consistent final review gate that reduces common implementation defects before human review.

Do not use as a substitute for implementation, for an unexplored design question, or to approve a change whose required tests have not been run.

Prerequisites

1. Read the request, acceptance criteria, repository instructions, and relevant architecture or contribution documentation.
2. Inspect the final diff, source-control status, affected call sites, adjacent production code, tests, build configuration, and continuous-integration workflow.
3. Identify the language version, package/dependency manifest, formatter, static checks, test runner, build command, deployment or migration boundary, and required external-state verification.
4. Gather actual command output for focused tests and every required project quality gate.

Completion: the review has a defined behavior contract, an exact change set, and real evidence rather than a producer summary.

Procedure

1. Reconstruct the intended behavior. State the observable behavior, affected users or callers, preserved behavior, failure modes, and explicit non-goals. Compare each changed hunk against that contract.
   • Completion: every change is necessary for the requested behavior or is identified as unrelated.
2. Follow data and control flow. Trace inputs through validation, domain logic, storage or network boundaries, error handling, outputs, and callers. Check empty, malformed, boundary, repeated, concurrent, delayed, and partially failed states when relevant.
   • Completion: the success path and credible failure paths are understandable without relying on unstated assumptions.
3. Check repository fit. Confirm that the change follows existing module boundaries, dependency direction, naming, configuration, error model, test layout, and public contract conventions. Prefer an established local pattern over a new abstraction.
   • Completion: a maintainer can find the changed behavior where they would naturally expect it.
4. Review interfaces and data contracts. Check types, serialization, nullability, ownership, lifecycle, ordering, compatibility, versioning, and caller-visible error behavior. Verify producers and consumers together when a contract changes.
   • Completion: no caller must guess the changed interface from implementation details.
5. Review maintainability. Remove unnecessary wrappers, speculative abstractions, catch-all modules, duplicate policy logic, dead code, broad refactors, narration comments, placeholder paths, debug output, and vague names. Keep comments only for non-obvious rationale or external constraints.
   • Completion: the diff reads as ordinary maintained code rather than a transcript of how it was produced.
6. Review safety and operations. Inspect untrusted inputs, authorization boundaries, secrets, logging, file and process boundaries, network timeouts, retries, idempotence, resource limits, concurrency, migrations, rollback behavior, and observability as applicable.
   • Completion: material operational risks are tested, bounded, or explicitly escalated.
7. Validate through the real quality loop. Run formatter, static analysis, type checks, focused regression tests, affected integration or contract tests, build, and any documented release check. When an external system changed, read back the exact target.
   • Completion: every claimed result has a command output, receipt, or observable state behind it.
8. Classify findings. Report each issue with affected behavior, evidence, severity, required correction, and test or verification needed. Separate blocking defects from optional improvements and unsupported suspicions.
   • Completion: a human can act on the review without rediscovering the problem.

Decision Points

Blind-Spot Checklist

• Does the implementation fulfill the stated behavior for both normal and failure paths?
• Do names, module locations, types, and errors make the change understandable to a maintainer who was not present for its creation?
• Is every new dependency, configuration value, file, and runtime action necessary and bounded?
• Are validation and authorization applied at the correct boundary, before side effects occur?
• Are retries, timeouts, ordering, idempotence, and resource use explicit where operations may repeat or fail?
• Did the change preserve existing public behavior unless a deliberate compatibility change is documented and tested?
• Do tests assert observable behavior and include the regression or edge case that justified the change?
• Did the required formatter, analysis, tests, build, and external read-back actually run?

Pitfalls

• Green-test tunnel vision: A passing narrow test does not prove architecture, security, compatibility, or operations are sound.
• Review by summary: Producer claims and commit messages are context, not evidence. Read the diff and execute the checks.
• Commentary as design: Long comments that narrate the change often hide a missing name, module boundary, or test.
• Abstraction inflation: More layers can make a small behavior harder to inspect, test, and reverse.
• Mock-only confidence: A mock proves a configured interaction, not necessarily that the real boundary behaves as required.
• Silent gate substitution: A build does not replace tests; tests do not replace a type check; a successful request does not replace external-state verification.

Verification

Before handoff, confirm that:

• every modified file and hunk maps to the requested behavior or an explicit required companion change;
• focused tests and all applicable repository gates ran with recorded results;
• the final diff has no unrelated churn, debug artifacts, generated noise, secrets, or local-machine assumptions;
• interfaces, errors, compatibility, and operational boundaries were reviewed at their callers and consumers;
• every blocking finding has a reproducible path and required corrective verification; and
• the result is reported as approved, requires changes, or incomplete, with evidence for that state.