Local Code Review Guide

Local Code Review Guide

Usage guide for local-code-review, grounded in its SKILL.md and README. This page is explanatory — the linked files are the contract.

What it reviews

The four local Git repository-state categories, detected separately: committed delta relative to a base, staged, unstaged, and untracked. No category is silently skipped without saying so in the report. See policies/repository-state.md.

Review-base policy compliance

The review base repository-state.md resolves (an explicit caller-supplied base, or this Skill's own resolution) is also checked against the repository's own review-base policy: an explicit statement in its instructions first, else its configured remote default-branch signal — never a hardcoded name like main, and never Git HEAD substituted for it merely because it's readily available. When neither signal resolves reliably (for example, no configured remote), the check is silent — a valid, expected outcome, not a fallback of last resort. A reliably established mismatch is reported as one blocking P0, naming both branches, before implementation findings. See How-the-Review-Model-Works and shared/policies/review-base-policy.md.

Invoking it

Plain language, no required syntax:

review my local changes before I push
run a local code review of the current diff
review the working tree against PROJECT-1234's acceptance criteria

Before you invoke it: the approval gate

This Skill must never be invoked automatically. Every invocation — the first review and every re-review after fixes — requires fresh, explicit user approval scoped to that one run. A standing preference, repository policy, or silence never qualifies; getting findings from one run is never authorization to run it again. Canonical: policies/invocation-approval.md.

Optional inputs

• Review context — requirements, a ticket, an ADR, a plan, or acceptance criteria, textual or a Jira/GitHub Issue reference. Focuses attention; never widens the review target. See Review-Context-and-Existing-Evidence.
• An associated PR reference — reconciles the local delta against that PR's prior findings and settled decisions as Existing Review Evidence. The local delta always stays the target.
• include_fix_prompt (default false) — appends a coding-agent-ready implementation prompt to a qualifying finding. Output-only; never changes severity or the decision. See docs/features/fix-prompt.md.
• human_review_output (default false, natural language, no flag) — a concise senior-engineer voice for the summary only. See docs/features/human-review-output.md.
• structured_review_result (default false) — appends one schema-versioned machine-readable JSON result after the unchanged human report. Output-only.
• 2 or more local repository roots (no flag, natural language) — composes them into one combined Review Target instead of reviewing a single repository. See Feature-Multi-Repository-Review-Target.
• Design reference, external contract context, workspace root — each must be supplied explicitly in the current invocation (never discovered from repository content) and is used only as read-only evidence: a design (typically Figma) for rendered inspection, a local repository path plus pinned revision for compatibility evidence, and one granted directory so a question can be resolved from a sibling repository's committed HEAD. None becomes a Review Target. See Feature-Rendered-UI-Inspection and Feature-Relationship-Aware-Context.

What you get back

One structured report: a Result line, what changed, optional context sections, Findings (P0/P1/P2, omitted when empty), and a mechanically derived REVIEW CLEAN / CHANGES REQUIRED decision (or REVIEW INCOMPLETE when coverage could not be completed — an unfinished review never renders as clean). Machine detail (SHAs, per-category counts) sits in a trailing metadata block, never ahead of the human-facing review. Full shape: templates/local-review-report.md.

A finding that a domain-specific deepening capability contributed (for example database or performance deepening) may carry an optional capability label — a provenance annotation only, never a second severity scale or a separate verdict. See Specialist-Depth-Review.

When the review considers running a repository-declared test/lint command, check the Validation section for whether it actually executed/failed/skipped/unavailable, and its sandbox, trusted-host, or host provenance if it ran. The repository's own tests run on your machine by default; say "run the tests in a sandbox" to opt out — see Feature-Runtime-Validation-Evidence.

What it never does

• Never edits files, commits, pushes, rebases, or creates branches.
• Never touches GitHub, even when a PR reference is supplied — reading PR context is read-only and never becomes publication.
• Never assumes a prior approval covers this invocation.
• Never launches a competing review: if another Code Review Agent already owns the same local branch/scope, it returns REVIEW ALREADY OWNED.
• Ships no "max loop" or re-review-count setting — that's an orchestration concern outside the Skill.

Re-reviewing after a fix

Every re-review needs its own fresh approval — this Skill is stateless between invocations. Its practical aid is the staged-delta fingerprint short-circuit (recognizing an unchanged staged delta), not a persistent memory of prior reviews. See runbooks/local-review.md for the recommended (not enforced) discipline.

Related feature pages

At-a-glance pages for capabilities this Skill supports: Feature-Runtime-Validation-Evidence · Feature-Requirement-Coverage · Feature-Human-Style-Review-Output · Feature-Multi-Repository-Review-Target · Feature-Human-Reasoning-Checkpoint. Full catalog: Feature-Pages.

Full contract

SKILL.md is the normative entry point; this guide only summarizes it.

How it is built: Local-Code-Review-Architecture.