Review

Review all current code changes using two-stage review.

Iron Law

> Two stages. In order. No shortcuts. > Stage 1 (Spec Compliance) MUST pass before Stage 2 (Code Quality) begins. > These are different questions: "Did you build the right thing?" vs "Did you build it well?"

Stage 1: Spec Compliance

Question: Does the code do what was intended?

1. Get the diff

`` git diff git diff --cached ``

1. Identify the intent — What was the goal of these changes? Check:

• Commit messages
• Related issue/PR descriptions
• task_plan.md if it exists
• Ask the user if intent is unclear

1. Verify spec compliance:

• Does the implementation match the stated goal?
• Are all requirements addressed?
• Are edge cases from the spec handled?
• Were the correct files modified (not random unrelated changes)?
• Do new features have corresponding tests?

1. Stage 1 Verdict:

• PASS — Implementation matches intent. Proceed to Stage 2.
• FAIL — Implementation misses requirements. List what's missing. STOP HERE.

Stage 2: Code Quality

Question: Is the code well-written? (Only after Stage 1 PASSES)

Read each changed file in full to understand context, then check:

Security

• Hardcoded secrets, API keys, passwords
• SQL injection, XSS, command injection
• Unsanitized user input
• Missing authentication/authorization checks
• Sensitive data in logs or error messages

Performance

• N+1 query patterns
• Missing database indexes on new columns
• Unnecessary re-renders (React)
• Large synchronous operations blocking event loop
• Missing pagination on list endpoints
• Memory leaks (unclosed resources, event listeners)

Code Quality

• Dead code or unused imports
• Duplicated logic (DRY violations)
• Functions too long (> 50 lines)
• Deeply nested conditionals (> 3 levels)
• Magic numbers or hardcoded strings
• Inconsistent naming with rest of codebase
• Missing error handling on external calls

Convention Compliance

• Does it follow existing codebase patterns?
• Consistent with CLAUDE.md rules?
• Test coverage for new code?
• Consistent file/function naming?

Output Format

## Code Review — Two-Stage

### Stage 1: Spec Compliance — PASS/FAIL
- Intent: [what the changes aim to do]
- Verdict: [pass/fail with reasoning]
- [If FAIL: what's missing or wrong]

### Stage 2: Code Quality — PASS/FAIL

#### Critical (must fix before merge)
- [file:line] [issue] — [why it matters]

#### Warning (should fix)
- [file:line] [issue] — [why it matters]

#### Suggestion (nice to have)
- [file:line] [suggestion]

#### Good Practices Observed
- [what was done well — reinforce good patterns]

Pre-Delivery Checklist

Before presenting the review, verify:

• [ ] All changed files were read in full (not just the diff)
• [ ] Stage 1 verdict is explicitly stated (PASS/FAIL)
• [ ] Every critical issue has a file:line reference
• [ ] Security section checked for OWASP top 5 at minimum
• [ ] No "looks fine" without specific evidence
• [ ] Existing test coverage verified for new code
• [ ] Convention compliance checked against CLAUDE.md
• [ ] Good practices section is not empty — always acknowledge what was done well

Anti-Rationalization

| Excuse | Rebuttal | |--------|----------| | "The spec is unclear so I'll skip Stage 1" | Then ASK for clarification. Unclear spec = ask, not skip. | | "This is just a small change, doesn't need full review" | Small changes cause big bugs. Review everything. | | "The code works, so the quality doesn't matter" | Working code that's unreadable is a liability. Quality always matters. | | "I wrote this code so I know it's correct" | You have blind spots on your own code. Review it as if someone else wrote it. | | "The security check is overkill for internal code" | Internal code gets exposed. Check it anyway. | | "Tests are passing so it must be fine" | Tests check behavior. Review checks maintainability, security, and conventions. |

Pre-Delivery Checklist

Before presenting the review, verify:

• [ ] git diff and git diff --cached were both read
• [ ] Every changed file was read in full (not just the diff)
• [ ] Stage 1 (spec compliance) was completed before Stage 2
• [ ] All security checks were performed (secrets, injection, auth)
• [ ] Convention compliance was checked against CLAUDE.md
• [ ] Each issue has file:line, description, and severity
• [ ] Good practices were acknowledged (not just negatives)
• [ ] No "probably fine" — every concern is flagged or verified

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: huzaifa525
• Source: huzaifa525/claude-code-optimizer
• License: MIT
• Homepage: https://www.npmjs.com/package/claude-code-optimizer

Install and usage instructions live in the source repository linked above.