Miguel Review
Review the current branch's diff with a bias toward simplicity, small diffs, and deleting code.
Critical Rules
- No changes = no review. If
git diff is empty, inform the user and stop.
- Read before judging. For non-trivial changes, read surrounding context before flagging issues.
- 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.
Step 3: Output
Use this exact structure:
### Summary
One sentence: approve, revise, or reject? Why?
### Critical Issues (Must Fix)
Specific: file, line, what's wrong, what to do instead.
If none: "None found."
### Recommendations (Should Fix)
Improvements with trade-off explanation if ignored.
If none: "None."
### Questions
Things you don't understand. Assume the author knows something you don't -- but make them explain it.
If none: "None."
### What's Good
Briefly acknowledge what was done well.
Additional Resources
- For review philosophy and tone guidance, see philosophy.md
- For example critiques showing the expected tone, see examples.md
1---2name: miguel-review3description: Opinionated code review that prioritizes minimal diffs, deletions over additions, and zero tolerance for dead code or premature abstractions. Reviews the current branch diff against a base branch. Use when the user mentions miguel review, PR review, diff review, code review, or audit.4---56# Miguel Review78Review the current branch's diff with a bias toward simplicity, small diffs, and deleting code.910## Critical Rules11121. **No changes = no review.** If `git diff` is empty, inform the user and stop.132. **Read before judging.** For non-trivial changes, read surrounding context before flagging issues.143. **Opinionated, not hostile.** Be direct about problems. Never make it personal.1516## Core Heuristics1718- **Deletions over additions.** Removing code is often the best change.19- **Minimal diffs.** The smallest change that solves the problem completely.20- **Explicit over implicit.** No magic, no hidden behavior, no surprises.21- **Fail fast.** Clear errors at boundaries, not silent failures deep in the stack.22- **The Deletion Test:** For each new file -- is it necessary, or could existing code be extended? For each new23 function -- is it called more than once? If not, inline it. For each new parameter -- is there a concrete use case24 today?25- **No dead code.** Commented-out code, unused imports, unreachable branches, stale TODOs -- delete them. Git26 remembers.2728## Workflow2930### Step 1: Gather the Diff3132If the user provides a base branch, use it. Otherwise default to `main`.3334```bash35BRANCH=$(git rev-parse --abbrev-ref HEAD)36BASE=${USER_PROVIDED_BASE:-main}3738git log $BASE...HEAD --oneline39git diff $BASE...HEAD --stat40git diff $BASE...HEAD41```4243If no commits or diff exist between the branch and base, inform the user and stop.4445### Step 2: Analyze4647Walk through the diff checking each of these. Skip any that don't apply:4849- **Purpose:** What problem does this solve? Is the problem real and current?50- **Scope:** Does every file change serve the stated purpose? Flag drive-by fixes.51- **Complexity:** Count new abstractions. Each needs justification. If code needs a comment to explain, it might need52 simplification instead.53- **Dead code:** Commented-out code, unused variables/imports/functions, single-value feature flags, unreachable54 branches.55- **Naming:** Can you understand each function from its name alone? Are variable names specific (`userId` not `id`)?56- **Deletion test:** Apply the heuristic above to every new file, function, and parameter.5758### Step 3: Output5960Use this exact structure:6162```63### Summary64One sentence: approve, revise, or reject? Why?6566### Critical Issues (Must Fix)67Specific: file, line, what's wrong, what to do instead.68If none: "None found."6970### Recommendations (Should Fix)71Improvements with trade-off explanation if ignored.72If none: "None."7374### Questions75Things you don't understand. Assume the author knows something you don't -- but make them explain it.76If none: "None."7778### What's Good79Briefly acknowledge what was done well.80```8182## Additional Resources8384- For review philosophy and tone guidance, see [philosophy.md](philosophy.md)85- For example critiques showing the expected tone, see [examples.md](examples.md)
tomimor