Branch Code Review (General)

Purpose

Perform a general code review on the current branch compared to the base branch (main by default), focusing on architecture, maintainability, and correctness.

Scope

• If $ARGUMENTS is provided, treat it as a scope (paths, diff range, or PR number).
• If no arguments are provided, review base...HEAD where base is detected (origin/main → origin/master fallback).

Workflow

1. Determine diff target

• Detect base branch:
• git symbolic-ref refs/remotes/origin/HEAD → extract main or master.
• If not available, try origin/main, then origin/master.

1. Enumerate change surface

• git diff --name-status base...HEAD
• git log --oneline base...HEAD
• Read the diff before diving into code.

1. Architecture pass

• Evaluate loose coupling, high cohesion, extensibility, and DRY.
• Check module boundaries and whether responsibilities are clearly separated.

1. Maintainability pass

• Keep files under ~500 lines unless necessary.
• Names are descriptive; public names are concise; internal names can be verbose.
• Comments explain why for non-obvious logic; remove redundant comments.
• Documentation is updated for behavior, usage, or interface changes.

1. Correctness and safety

• Validate logic, edge cases, and error handling.
• Look for regressions, config mismatches, or hidden coupling.

1. Tests

• Ensure tests exist and are meaningful for the change surface.
• Prefer tests that would fail on broken behavior.

Best-Practice Signals (from authoritative guidance)

• Review design and interactions first; validate overall intent. (Google Eng Practices)
• Read every changed line in logical sequence; expand context if needed. (Google + Microsoft)
• Focus on correctness, readability/maintainability, and test quality. (Microsoft)
• Use structured checklists to avoid missing issues. (Atlassian)

Repo-Specific Context

This repo is evolving toward extensible planning/content management. Favor:

• Clear interfaces for future content types beyond plans.
• Minimal cross-package coupling.
• Extensible, composable APIs (avoid one-off branching).
• Config/format stability to support long-lived plans and migrations.

Output Format

Follow the repo review style:

• Findings first, ordered by severity.
• Include file references and concrete evidence.
• If no issues, say so explicitly and list residual risks or testing gaps.

Use this structure:

## Findings
- 🔴 Critical: ...
- 🟠 High: ...
- 🟡 Medium: ...
- 🟢 Low: ...

## Questions / Assumptions
- ...

## Tests
- Suggested: ...