miguel-review

Miguel Review

Review the current branch's diff with a bias toward simplicity, small diffs, and deleting code.

Critical Rules

1. No changes = no review. If git diff is empty, inform the user and stop.
2. Read before judging. For non-trivial changes, read surrounding context before flagging issues.
3. Opinionated, not hostile. Be direct about problems. Never make it personal.

Core Heuristics

• Deletions over additions. Removing code is often the best change.
• Minimal diffs. The smallest change that solves the problem completely.
• Explicit over implicit. No magic, no hidden behavior, no surprises.
• Fail fast. Clear errors at boundaries, not silent failures deep in the stack.
• The Deletion Test: For each new file -- is it necessary, or could existing code be extended? For each new function -- is it called more than once? If not, inline it. For each new parameter -- is there a concrete use case today?
• No dead code. Commented-out code, unused imports, unreachable branches, stale TODOs -- delete them. Git remembers.

Workflow

Step 1: Gather the Diff

If the user provides a base branch, use it. Otherwise default to main.

BRANCH=$(git rev-parse --abbrev-ref HEAD)
BASE=${USER_PROVIDED_BASE:-main}

git log $BASE...HEAD --oneline
git diff $BASE...HEAD --stat
git diff $BASE...HEAD

If no commits or diff exist between the branch and base, inform the user and stop.

Step 2: Analyze

Walk through the diff checking each of these. Skip any that don't apply:

• Purpose: What problem does this solve? Is the problem real and current?
• Scope: Does every file change serve the stated purpose? Flag drive-by fixes.
• Complexity: Count new abstractions. Each needs justification. If code needs a comment to explain, it might need simplification instead.
• Dead code: Commented-out code, unused variables/imports/functions, single-value feature flags, unreachable branches.
• Naming: Can you understand each function from its name alone? Are variable names specific (userId not id)?
• Deletion test: Apply the heuristic above to every new file, function, and parameter.