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:
Always load:.claude/rubric/base.md and .claude/rubric/product-quality.md
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).
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
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:
Read the file
Understand the issue
Use Edit tool to fix
Verify fix compiles: run npm run build or npx tsc --noEmit or language-appropriate check
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: Pitfalls
Known pitfalls are maintained in canon/pitfalls/SKILL.md. If you discover a new recurring pattern, note it in the report output — it can be added to the pitfalls canon in a future release.
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