Pre-Push Code Review

Review and fix unpushed commits before they reach the remote repository.

Phase 1: Identify Changes

Determine which commits haven't been pushed to the remote repository. Use git diff origin/<branch>..HEAD to get the full diff of unpushed changes. Show the user which commits will be reviewed.

If there is no remote tracking branch yet, diff against origin/main .

Phase 2: Locate Relevant Specifications

Check if there's a spec for the feature being worked on:

• Examine the current branch name for feature indicators

• Look in the specs directory for matching feature folders

• Review all documents in the feature folder: requirements, design, tasks, and decision log

• If no spec exists, proceed with general review only

Phase 3: Launch Review Agents in Parallel

Use the Agent tool to launch all agents concurrently in a single message. Pass each agent the full diff so it has the complete context.

Agent 1: Code Reuse Review

For each change:

• Search for existing utilities and helpers that could replace newly written code. Use Grep to find similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones.

• Flag any new function that duplicates existing functionality. Suggest the existing function to use instead.

• Flag any inline logic that could use an existing utility — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.

Agent 2: Code Quality Review

Review the same changes for hacky patterns:

• Redundant state: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls

• Parameter sprawl: adding new parameters to a function instead of generalizing or restructuring existing ones

• Copy-paste with slight variation: near-duplicate code blocks that should be unified with a shared abstraction

• Leaky abstractions: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries

• Stringly-typed code: using raw strings where constants, enums (string unions), or branded types already exist in the codebase

Agent 3: Efficiency Review

Review the same changes for efficiency:

• Unnecessary work: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns

• Missed concurrency: independent operations run sequentially when they could run in parallel

• Hot-path bloat: new blocking work added to startup or per-request/per-render hot paths

• Unnecessary existence checks: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error

• Memory: unbounded data structures, missing cleanup, event listener leaks

• Overly broad operations: reading entire files when only a portion is needed, loading all items when filtering for one

Agent 4: Spec & Documentation Review (only if spec exists)

• Spec adherence: Verify implementation matches requirements and design. Identify divergences. Ensure divergences are documented in the decision log.

• Documentation: Check if README, CLAUDE.md, or other docs need updates to reflect the changes.

• Testing gaps: Verify presence of appropriate tests for new/modified code. Check that tests test behavior, not implementation.

Phase 4: Fix Issues

Wait for all agents to complete. Aggregate their findings and fix each issue directly.

Constraints:

• Do not modify test files unless fixing an actual bug (e.g., a test that tests the wrong thing or has a genuine error). Refactoring production code must not require test changes — if it would, reconsider the refactoring approach.

• If a finding is a false positive or not worth addressing, skip it without debate.

Phase 5: Verify

After all fixes are applied:

• Run the project's test suite (use Makefile commands if available). All tests must pass.

• Run linters and validators as specified in project configuration.

• If any test fails, investigate whether the fix introduced a regression and revert or adjust the fix — do not modify the test to make it pass.

Phase 6: Generate Implementation Explanation (if spec exists)

Use the explain-like skill (invoke the Skill tool with skill="explain-like") to generate explanations of the implementation at multiple expertise levels. Write the output to specs/{feature_name}/implementation.md .

Use the explanation as a validation mechanism:

• If any requirement from the spec cannot be clearly explained, flag it as potentially incomplete.

• If the explanation reveals logic that doesn't align with the design, flag it as a divergence.

• Add a "Completeness Assessment" section summarizing: what's fully implemented, what's partially implemented, and what's missing.

Phase 7: Summary

Provide a clear verdict: Ready to push, Needs fixes (with must-fix list), or Requires discussion (with architectural concerns).

List what was fixed automatically and what still needs attention.