gemini-review

name	gemini-review
description	Hard-ass code review via Gemini. ALL issues must be fixed. No exceptions.

/gemini-review [path]

Hard-ass code review using Gemini. Finds issues AND fixes them. Senior Google engineer style - no handholding, no false praise, no excuses.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"gemini-scan-fix","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Fix code toward what a master craftsperson would be proud of.

When fixing issues, ensure the result looks like it was written by a skilled human engineer, not generated by AI.

AI Antipatterns to ACTIVELY FLAG AND FIX

Gemini is instructed to find these, and you MUST fix them:

• Over-abstraction (factories/wrappers used once → inline or remove)
• Defensive paranoia (impossible null checks → remove)
• Reimplementing stdlib (custom utils when libraries exist → use the library)
• Comment spam (obvious comments → delete)
• Speculative features (unused config → remove)
• Enterprise patterns in simple code → simplify

Human Craft Standard for Fixes

After fixing, code should:

• Have no line a senior engineer would question
• Be simpler than before, not more complex
• Solve actual problems, not imaginary ones

The best fix often removes code rather than adding it.

---

Scope Constraint (MANDATORY)

Fix ALL findings for production readiness. Every issue gets fixed. No deferring, no "backlog for next cycle," no "appropriate for MVP."

ALLOWED:

• Change logic within an existing function
• Add validation/checks to existing code paths
• Fix crypto/security bugs in existing implementations
• Add private helper methods within existing files
• Add config entries, constants, enums to existing files
• Add interfaces to existing files if needed for proper typing
• Restructure function internals (keep same signature)

FORBIDDEN:

• Adding new source files (config files are OK)
• Moving code between files
• Adding new external dependencies

If a finding seems to require restructuring: fix it anyway by restructuring within the existing file. The only acceptable unfixed items are findings that require adding new external dependencies — report those with a one-line explanation.

---

Target

If a path argument is provided, review that file/directory. If no argument, review recently modified files (git diff/log).

Process (Two Steps)

Step 0: Load Rubric

Read .claude/rubric/AUTO-DETECT.md for the detection table. Then:

1. Always load: .claude/rubric/base.md and .claude/rubric/product-quality.md
2. Auto-detect domains: Check target files against the detection table. Load matching domain rubrics (.claude/rubric/web-api.md, .claude/rubric/data-persistence.md, .claude/rubric/cli.md, .claude/rubric/microservice.md).
3. Extract Review Criteria: From each loaded rubric, collect the numbered items under ## Review Criteria. Combine into a single criteria list for the Gemini context.

If a rubric file doesn't exist, skip it and continue.

Step 1: IDENTIFY Issues (Do Not Fix Yet)

1a. Find Code to Review

Find target files:

• If path provided, use that
• Otherwise, find recently modified files using git diff or git log
• Look in: src/, lib/, app/, and project root

If NO code exists, output "no code to review" and stop.

1b. Read All Target Code

Read ALL files in scope completely. Do not skim.

1c. Call Gemini (MANDATORY)

For each source file (one file per call, not concatenated):

mcp__gemini-reviewer__gemini_review
  code: <contents of this single file>
  focus: "general"
  context: "PRODUCTION READINESS review for {filename}. Check against these criteria: {RUBRIC_CRITERIA}. Also note if public APIs lack tests (Test Coverage — handled by testing phase). SEVERITY: CRITICAL = exploitable vulnerability, data loss, crash in production. HIGH = would cause incidents, missing critical validation. MEDIUM = poor practice, minor gaps. LOW = style, naming. OUTPUT FORMAT: FINDING: {category} | {severity} | {description} | {file:line}"

Replace {RUBRIC_CRITERIA} with the combined Review Criteria from all loaded rubric files, numbered sequentially.

If tool unavailable, output: GEMINI_ERROR: tool not available

1d. List All Issues

Output issues in this format:

ISSUES_FOUND:
1. [CRITICAL] description (file:line)
2. [HIGH] description (file:line)
3. [MODERATE] description (file:line)
...

IDENTIFICATION_COMPLETE: yes

Step 1e: Product Quality Review (MANDATORY)

After the code review, do a separate product-level review. This catches bad products built with good code.

Call Gemini again with focus "adversarial":

mcp__gemini-reviewer__gemini_review
  code: <paste the main entry point / CLI / config code>
  focus: "adversarial"
  context: "PRODUCTION READINESS — user experience gate. Review as a user deploying this to production. Check against the product quality criteria: {PRODUCT_QUALITY_CRITERIA}. Flag any issue that would cause a production incident or require rollback."

Replace {PRODUCT_QUALITY_CRITERIA} with the Review Criteria from .claude/rubric/product-quality.md (loaded in Step 0), numbered sequentially.

Add any product quality issues to the ISSUES_FOUND list with severity [HIGH] or [MODERATE].

Step 2: FIX All Issues

For EACH issue:

1. Read the file
2. Understand the issue
3. Use Edit tool to fix
4. Verify fix compiles: run npm run build or npx tsc --noEmit or language-appropriate check
5. Mark as FIXED

If you cannot fix an issue:

Document with specific reason (e.g., "requires architectural change", "in third-party code")

Maximum unfixed issues:

• CRITICAL/HIGH: 0 allowed (must fix ALL)
• MODERATE/LOW: 2 allowed maximum

Output Format

## Gemini Scan + Fix: [target]

### Summary

| Metric | Value |
|--------|-------|
| Files scanned | N |
| Issues found | N |
| Issues fixed | N |
| Cannot fix | N |

### Issues Fixed ✅

1. **[file:line]** [SEVERITY] — description
   - Fix applied: [what was changed]

### Cannot Fix ⚠️

1. **[file:line]** [SEVERITY] — description
   - Reason: [specific reason]

### Files Modified

| File | Changes |
|------|---------|
| path/to/file.ts | Fixed 3 issues |

---
GEMINI_RESULT: called - [N] issues found
ISSUES_FIXED: N
CANNOT_FIX: N
GEMINI_REVIEW_COMPLETE: yes

Final: Record Lessons Learned

After fixing all issues, record NEW findings so earlier phases learn from them.

Write to TWO files:

1. Project-local: .claude/lessons.md

Append the specific finding with file paths and context:

## {date} - {target path}
### Gemini Found (phase 6)
- {CATEGORY}: {specific description with file:line} → {which earlier phase should catch this and how}

2. Universal: .claude/universal-lessons.md

Read this file first. If the general pattern is already listed, skip. If it's a NEW general pattern not already covered, append it to the appropriate section (LOGIC Patterns, DESIGN Patterns, CODE_QUALITY Patterns, DUPLICATION Patterns, or Gemini False Positive Patterns). Write the general rule, not the project-specific instance:

### {Pattern Name}
- {General description of the pattern, not tied to specific files} → {how to avoid it}

Categories: LOGIC, DESIGN, CODE_QUALITY, DUPLICATION, AI_SMELL

Also record false positive patterns that Gemini consistently flags incorrectly:

- **"{pattern description}"** — {why it's not applicable in this context}

If no new lessons were learned (already in both files), skip this step.

Evidence Checklists (MANDATORY)

After fixing all issues, produce two evidence checklists. Write each to .claude/evidence/ (create directory if needed).

Checklist 6a: Error Messages

Review EVERY console.error, console.log, throw new Error, and reject( call. Write to .claude/evidence/gemini-6a.md:

# Evidence: Gemini 6a — Error Messages

| Location | Item | Verdict | Reasoning |
|----------|------|---------|-----------|
| src/auth.ts:15 | throw new Error("Invalid token") | PASS | Descriptive, no secrets leaked |
| src/db.ts:42 | console.log(query) | FAIL | Logs raw query which may contain user data |

Checklist 6b: Input Boundaries

Review EVERY CLI arg read, fs.readFile, and process.env access. Write to .claude/evidence/gemini-6b.md:

# Evidence: Gemini 6b — Input Boundaries

| Location | Item | Verdict | Reasoning |
|----------|------|---------|-----------|
| src/cli.ts:8 | process.argv[2] | PASS | Validated before use |
| src/config.ts:3 | process.env.API_KEY | FAIL | No fallback or error if missing |

Every row must have a PASS or FAIL verdict. No blanks. The machine gate validates row counts against codebase counters — incomplete checklists block the pipeline.

Rules

• MUST CALL GEMINI - This skill requires the Gemini MCP tool
• MUST FIX - All CRITICAL and HIGH issues must be fixed
• VERIFY - Check each fix compiles before moving on
• NO EXCUSES - "Requires architectural change" is only valid for truly massive refactors
• COMPLETE - Review and fix all files in scope

Forbidden

• Marking issues as "application-level concern"
• Saying "requires application code" without trying
• Punting to "future work"
• Skipping because it's "operational"
• Making judgment calls about what's worth fixing
• Leaving CRITICAL or HIGH issues unfixed

When to Use

• Pre-commit quality gate
• Before PR submission
• After implementing a feature
• Code cleanup with teeth

Comparison

Skill	Reviews	Fixes
/gemini-scan	✓	✗ (read-only)
/gemini-review	✓	✓ (mandatory)
/adversarial-review	✓	✓ (security focus)