Skip to content

Local Code Review Guide

Jump to bottom
amirbena edited this page Sep 18, 2026 · 6 revisions

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.

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. 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 or trusted-host provenance if it ran — 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.
  • 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. Full catalog: Feature-Pages.

Full contract

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

Wiki Page Map

Page What it covers
Home Wiki entry point: what the two Skills are and where to go next.
Getting-Started First steps to package and run either Skill.
Choosing-a-Review-Skill How to decide between local-code-review and github-pr-review.
How-the-Review-Model-Works Concept-level walkthrough of the review pipeline shared by both Skills.
Architecture-Overview Component-level map of how the repository's pieces fit together.
Specialist-Depth-Review When and how a review goes deeper than its base pass.
Local-Code-Review-Guide Usage guide for reviewing local, not-yet-PR'd Git changes.
GitHub-PR-Review-Guide Usage guide for reviewing an existing GitHub Pull Request.
Review-Context-and-Existing-Evidence How optional requirements/context and prior review evidence are supplied.
Feature-Pages Index of per-feature capability pages and their shared template.
Feature-Delta-Re-Review How a re-review scopes itself to only what changed since the last pass.
Feature-GitHub-Publication-and-Authorization What a PR review publishes to GitHub and under what authority.
Feature-Human-Style-Review-Output The senior-engineer-voice prose summary output option.
Feature-Requirement-Coverage How supplied requirements are checked and reported as covered or not.
Feature-Runtime-Validation-Evidence How a review can execute commands or reproductions as evidence.
Severity-and-Decision-Model The P0/P1/P2 severity levels and how the merge decision is derived.
Packaging-and-Portability How the Skills go from source repository to a standalone archive.
Development-Workflow Contributor guide for working on this repository itself.
Benchmark-Testing Orientation to this repository's own review-quality benchmark pipeline.
Repository-Documentation-Map Where each concern's canonical, authoritative source lives.
AI-Code-Review-Landscape Neutral snapshot comparing this project against other AI code-review products.
FAQ Short, practical answers to common questions.

Clone this wiki locally