Fresh Eyes Review

Systematic pre-commit quality gate → checklist-based review → findings → summary.

<when_to_use>

Pre-commit code review and quality gates
Pre-merge pull request reviews
Systematic code audits before deployment
Quality verification for critical changes
Second-opinion review requests

NOT for: quick sanity checks, trivial typo fixes, formatting-only changes

</when_to_use>

<announcement_protocol>

Starting Review

Review Scope: { files/areas under review } Focus Areas: { specific concerns or general quality gate } Checklist: { full or targeted categories }

During Review

Emit findings as discovered:

{SEVERITY} {FILE_PATH}:{LINE} — { issue description }
Impact: { consequences if shipped }
Fix: { concrete remediation }

Completing Review

Review Complete

Findings Summary:

◈ Severe: {COUNT} — blocking issues
◆ Moderate: {COUNT} — should fix before merge
◇ Minor: {COUNT} — consider addressing

Recommendation: { ship / fix blockers / needs rework }

{ detailed findings below if any found }

</announcement_protocol>

Type Safety

✓ No any types without justification comment
✓ Null/undefined handled explicitly (optional chaining, nullish coalescing)
✓ Type guards used for union types
✓ Discriminated unions for state machines
✓ Generic constraints specified where needed
✓ Return types explicit on public functions
✓ No type assertions without safety comment

Error Handling

✓ All error paths handled (no silent failures)
✓ Meaningful error messages with context
✓ Errors propagated or logged appropriately
✓ Result types used for expected failures
✓ Try/catch blocks have specific error handling
✓ Promise rejections handled
✓ Resource cleanup in finally blocks

Security

✓ User input validated before use
✓ No hardcoded secrets or credentials
✓ Authentication/authorization checks present
✓ Parameterized queries (no SQL injection)
✓ XSS prevention (sanitized output)
✓ CSRF protection where applicable
✓ Sensitive data encrypted/hashed
✓ Rate limiting on public endpoints

Testing

✓ Tests exist for new functionality
✓ Edge cases covered
✓ Error scenarios tested
✓ Actual assertions (not just execution)
✓ No test pollution (proper setup/teardown)
✓ Mocks used appropriately (not overused)
✓ Test names describe behavior
✓ Integration tests for critical paths

Code Quality

✓ Names reveal intent (functions, variables, types)
✓ Functions <50 lines (single responsibility)
✓ Files <500 lines (consider splitting)
✓ No magic numbers (use named constants)
✓ DRY violations eliminated
✓ Nested conditionals <3 deep
✓ Cyclomatic complexity reasonable
✓ Dead code removed

Documentation

✓ Public APIs have JSDoc/TSDoc
✓ Complex algorithms explained
✓ Non-obvious decisions documented
✓ Breaking changes noted
✓ TODOs have context and owner
✓ README updated if behavior changes
✓ Examples provided for complex usage

Performance

✓ No obvious N+1 queries
✓ Appropriate data structures used
✓ Unnecessary allocations avoided
✓ Heavy operations async/batched
✓ Caching where beneficial
✓ Database indexes considered

Rust-Specific (when applicable)

✓ rustfmt and clippy passing
✓ Result preferred over panic
✓ No unwrap/expect outside tests/startup
✓ Ownership/borrowing idiomatic
✓ Send/Sync bounds respected
✓ Unsafe code justified with comments
✓ Proper error types (thiserror/anyhow)

</checklist> <stages>

1. Announce (activeForm: Announcing review)

Emit starting protocol:

Scope of review
Focus areas
Checklist approach (full or targeted)

2. Checklist (activeForm: Running checklist review)

Systematically verify each category:

Type Safety → Error Handling → Security → Testing → Quality → Docs → Performance
Flag violations immediately with severity
Note clean areas briefly

3. Deep Dive (activeForm: Investigating findings)

For each finding:

Verify it's actually a problem (not false positive)
Assess severity and impact
Determine concrete fix
Check for pattern across codebase

4. Summarize (activeForm: Compiling review summary)

Emit completion protocol:

Findings count by severity
Recommendation (ship / fix blockers / rework)
Detailed findings list
Optional: patterns noticed, suggestions for future

Load the maintain-tasks skill for tracking review stages.

</stages>

<finding_format>

{SEVERITY} {FILE_PATH}:{LINE_RANGE}

Issue: { clear description of problem }

Impact: { consequences if shipped — security risk, runtime error, maintenance burden, etc }

Fix: { concrete steps to remediate }

Pattern: { if issue appears multiple times, note scope }

Example:

◈ src/auth/login.ts:45-52

Issue: Password compared using == instead of constant-time comparison

Impact: Timing attack vulnerability — attacker can infer password length and content through response timing

Fix: Use crypto.timingSafeEqual() or bcrypt's built-in comparison

Pattern: Single occurrence

</finding_format>

<severity_guidance>

◈ Severe (blocking):

Security vulnerabilities
Data loss risks
Runtime crashes in common paths
Breaking changes without migration
Test failures or missing critical tests

◆ Moderate (should fix):

Type safety violations
Unhandled error cases
Poor error messages
Missing tests for edge cases
Significant code quality issues
Missing documentation for public APIs

◇ Minor (consider addressing):

Code style inconsistencies
Overly complex but functional code
Minor performance optimizations
Documentation improvements
TODOs without context
Naming improvements

</severity_guidance>

Loop: Scan → Verify → Document → Next category

Announce review — scope, focus, approach
Run checklist — systematically verify each category
Document findings — severity, location, issue, impact, fix
Investigate patterns — does finding repeat? Broader issue?
Deep dive blockers — verify severity assessment, ensure fix is clear
Compile summary — counts by severity, recommendation
Deliver findings — completion protocol with detailed list

At each finding:

Verify it's actually a problem
Assess impact if shipped
Determine concrete fix
Note if pattern across files

</workflow> <validation>

Before completing review:

Check coverage:

✓ All checklist categories verified?
✓ Both happy path and error paths reviewed?
✓ Tests examined for actual assertions?
✓ Security-sensitive areas given extra scrutiny?

Check findings quality:

✓ Severity accurately assessed?
✓ Impact clearly explained?
✓ Fix actionable and concrete?
✓ False positives eliminated?

Check recommendation:

✓ Aligned with findings severity?
✓ Blockers clearly marked?
✓ Path forward unambiguous?

</validation> <rules>

ALWAYS:

Announce review start with scope and focus
Run systematic checklist, don't skip categories
Emit findings as discovered, don't batch at end
Assess severity honestly (err toward caution)
Provide concrete fixes, not just complaints
Complete with summary and recommendation
Mark false positives if checklist item doesn't apply
Consider patterns (single issue or systemic?)

NEVER:

Skip checklist review for "quick check"
Assume code is safe without verification
Flag style preferences as blockers
Provide vague findings without fix guidance
Approve severe findings "for later fix"
Complete review without announcement protocol
Miss security checks on user input paths
Ignore test quality (execution != validation)

</rules> <references>

Core methodology:

checklist.md — extended checklist details, examples, severity guidance

Related skills:

codebase-analysis — evidence-based investigation (foundation for review)
debugging — structured bug investigation

</references>

code-review