with one click
review-code
Junior-dev comprehension check on changed code. Per-file design review (role, assumed knowledge, wheel-reinvention), per-unit logic review (WHAT/WHY/LOGIC/SIMPLER), then a holistic diff review. Does NOT modify code.
Menu
Junior-dev comprehension check on changed code. Per-file design review (role, assumed knowledge, wheel-reinvention), per-unit logic review (WHAT/WHY/LOGIC/SIMPLER), then a holistic diff review. Does NOT modify code.
Switch to unattended/solo mode for research and long-running tasks. Push through friction instead of pausing. Only invoked on explicit /unattended — never auto-load.
Writing, structuring, and maintaining project documentation. Auto-loaded when creating or updating docs, mkdocs sites, architecture pages, or any markdown documentation.
Visual and structural documentation review. Screenshots live rendered pages, passes to Gemini vision for readability/colour/diagram analysis. Separate pass for structure, acronyms, assumed knowledge, and factual accuracy (broken links, stale code refs, image/claim mismatches). Persona is a junior researcher with no domain context.
Generate visual diagrams (flowcharts, matrices, architecture, org charts, quadrants, mind maps, etc.) with a render-and-review feedback loop. Use when the user asks for a diagram, chart, visualization, flowchart, or "visual". Picks the right tool for the data shape (Mermaid / D2 / raw SVG / Graphviz / quadrantChart) and iterates until the rendered output is actually readable.
Drive the NixOS + Hyprland desktop programmatically — window focus, keyboard input, screenshots, clipboard, VNC, and Chromium via CDP. Use when a task requires headful UI interaction, visual verification, or browser automation.
Run long-running or interactive commands in a tmux session the user can watch and interact with. Use this for any command expected to take >30s, dev servers, watch modes, builds, tests, REPLs, migrations, or anything the user might need to Ctrl+C or send input to. Skip for quick one-shot commands (<30s, no prompts).
| name | review-code |
| description | Junior-dev comprehension check on changed code. Per-file design review (role, assumed knowledge, wheel-reinvention), per-unit logic review (WHAT/WHY/LOGIC/SIMPLER), then a holistic diff review. Does NOT modify code. |
What: Three passes on every file changed since main — architectural sweep of the full codebase, per-file design + unit review, then the full diff as one.
Why: Claude reviews its own code with full project context. A stateless external call with no prior context catches what the author normalises away: unclear responsibilities, hidden assumptions, wheel-reinvention. Tool choice per pass matches the intended reviewer's information access.
/review-code
/review-code path/to/specific/file.go
Without an argument: all files changed or added since main.
git diff --name-only main..HEAD
git status --short | grep '^?? '
Supported: .go, .py, any source file with recognisable structure.
Skip: generated files (*.pb.go, *_generated.go, docs/grading/api/).
Run from project root. Gemini reads the codebase natively — no piping needed.
gemini -p 'ARCH_PROMPT'
ARCH_PROMPT:
Read all source files in this project (excluding vendor/, node_modules/, generated files like *.pb.go and *_generated.go).
You are a senior architect reviewing this entire codebase cold. You have NOT worked on this project before.
Answer 5 questions. No code. Be specific — name files and functions where relevant.
ARCHITECTURE_INTENT:
One paragraph: what architectural pattern does this codebase appear to be following?
Name the layers and boundaries you can identify.
DRIFT:
NONE — or — FLAG: any file or package that has drifted from the architectural pattern above.
Specifically: what layer does it CLAIM to be in vs what layer is it ACTUALLY operating in?
CONSISTENCY:
CLEAN — or — FLAG: the same problem solved differently in different parts of the codebase.
Name the specific files and what pattern each uses.
COUPLING:
CLEAN — or — FLAG: inappropriate dependencies between layers or modules.
What is reaching into what it shouldn't? Be specific about file and function names.
ORPHANED:
NONE — or — FLAG: code left over from a previous design iteration — abstractions with one
implementer, interfaces nobody uses, patterns not followed elsewhere.
One call per changed file. Uses llm -a — model sees only this file, enforcing the cold-read frame.
llm -m gemini-2.5-flash 'FILE_PROMPT' -a <file>
FILE_PROMPT (substitute <FILENAME>):
You are a senior developer and junior developer reading this file cold — no prior context about the project.
Answer all questions below. No code. File: <FILENAME>
--- DESIGN ---
INTENT: One sentence — what problem is this file solving?
CLEAN_ROOM: You are designing this from scratch, no constraints from the existing code.
In 3–4 sentences: what responsibilities would it own, what would it NOT own, and what
would the key design choices be?
DIVERGENCE: What is the single biggest difference between your clean-room design and what
actually exists? If the current design is reasonable, say so and why.
--- RULES ---
WEAK_CONTRACTS:
NONE — or — FLAG: any caller/callee boundary weaker than the signature suggests:
- unused parameters, or parameters derivable from others already passed
- struct passed when only one field is used; any/string where a narrower type would compile-enforce the contract
- indirection (interface, wrapper, extra layer) with no comment explaining why it exists
TEST_CONTRACTS:
NONE — or — FLAG: anything a reader must verify outside this file to trust the test:
- fixture values with no comment on whether they're placeholders or meaningful
- fields documented as "recorded for assertion" where nothing asserts
- hardcoded slices when an authoritative constant/map exists to range over
SCOPE:
CLEAR — or — FLAG: is the file doing more than one job? one function carrying most of the weight?
DEPTH:
CLEAN — or — FLAG: functions with 3+ nesting levels or branching that obscures the happy path
NAMING:
CLEAN — or — FLAG: any name that surprised you when you read the body. Also flag:
- test fixtures named informally with no comment on what they simulate
- fields named with generic suffixes (idx, cursor, counter, flag) where the state machine is unexplained
REINVENTING:
NO — or — FLAG: anything here that exists in the standard library, a well-known ecosystem
library, or already elsewhere in this project — including test utilities, retry/polling logic,
string manipulation, file handling, HTTP helpers.
SIMPLER:
NO — or — FLAG: a fundamentally simpler approach to what this file does — one sentence, no code
One call per changed file covering all units. Uses llm -a — model sees only this file.
llm -m gemini-2.5-flash 'UNIT_PROMPT' -a <file>
UNIT_PROMPT (substitute <FILENAME>):
You are a junior developer reading this code for the first time.
File: <FILENAME>
For EACH top-level function, method, class, or def in this file, answer 4 questions.
Emit the unit name as a header before each set of answers.
Do NOT write code. Do NOT refactor.
WHAT: one sentence — what it does and what it returns. Say so if unclear.
WHY: one sentence — why does it exist separately? what breaks if inlined or removed?
LOGIC: CLEAR — or — FLAG: which step confused you and why
SIMPLER: NO — or — YES: one sentence describing a simpler approach, no code
One call with the full diff after all per-file passes.
git diff main..HEAD | llm -m gemini-2.5-flash 'HOLISTIC_PROMPT'
HOLISTIC_PROMPT:
You are a junior developer who has just read a code diff.
Your ONLY job is to answer 3 questions. Do NOT write code.
COHERENT: CLEAR — or — FLAG: do the changes hang together as one coherent unit of work? what seems inconsistent?
COMPLETE: CLEAR — or — FLAG: is anything obviously missing from what the diff seems to be trying to do?
SURPRISES: NONE — or — FLAG: any file or change that doesn't fit with the rest?
Write to report only if any answer across all passes contains FLAG or YES.
All clear → print review complete — no flags, write nothing.
docs/appendix/reviews/YYYY-MM-DD-<basename>.md — one file per review run.
Structure: Architectural section (Pass 0), then per file: File and Units subsections together, then Holistic section (Pass 3). Append a row to docs/appendix/reviews/index.md. Leave unstaged.
gemini CLI — native filesystem access, full 1M context for cross-file architectural analysisllm -m gemini-2.5-flash — isolated single-file calls, cold-read frame enforced via -allm -m gemini-2.5-flash — diff piped via stdin, no filesystem access needed