Skip to content

Local Code Review Architecture

Jump to bottom
amirbena edited this page Oct 15, 2026 · 4 revisions

Local Code Review Architecture

This page shows how local-code-review is built: how a review of local Git changes flows from invocation to a returned report, and what is specific to this mode. For how to use it, see Local-Code-Review-Guide. Back to Architecture-Overview.

local-code-review is an adapter over the Shared-Review-Engine. It acquires a local Git change as the Review Target, hands it to the engine, and returns what the engine produces as a report.

The flow

sequenceDiagram
    actor U as Caller
    participant L as local-code-review
    participant G as Local Git
    participant E as Shared engine

    U->>L: explicit approval for this run
    L->>G: read-only inspection of the four state categories
    G-->>L: committed / staged / unstaged / untracked changes
    L->>L: Review Target + staged fingerprint
    opt context or PR reference supplied
        L->>L: resolve context, read prior evidence
    end
    L->>E: Review Target + context
    E-->>L: findings + Decision
    L-->>U: report (nothing written, nothing published)
Loading

What is specific to local mode

Explicit invocation. The Skill never runs on its own. Every run — including a re-review after fixes — needs fresh, explicit approval from the user for that run. Approval from an earlier run does not carry over. Owner: invocation-approval.md.

Four state categories. Local work exists in several states, and the Skill inspects each separately rather than blending them:

Category Meaning
committed commits on the branch relative to a base
staged changes added to the index
unstaged tracked changes not yet staged
untracked new files Git does not yet track

The report attributes each finding to its category. Owner: repository-state.md.

Staged fingerprint. A fingerprint of the staged changes is computed so a later re-review can tell whether the staged content changed.

Optional context. A caller may supply requirements, a Jira key or GitHub Issue, a design note, or a reference to an associated PR. These focus the review and let it reason about intended scope. They never widen the Review Target; the local changes remain the only thing reviewed. A Jira key that cannot be resolved stops the review as JIRA CONTEXT UNRESOLVED rather than being guessed at. A PR reference supplies prior review evidence, not a new target.

Optional multi-repository target. A caller may name two or more local repositories to be reviewed as one combined target. Omitted, behavior is unchanged. See Feature-Multi-Repository-Review-Target.

Read-only, no GitHub mutation. The Skill does not edit files, commit, push, or change anything on GitHub. It also does not keep state between invocations. A command may be run as validation evidence only under the narrow rules in Feature-Runtime-Validation-Evidence.

What it does not have. No temporary checkout, no parallel workers (it is a single bounded invocation with no worker fan-out), no inline comments or approval events — those belong to the GitHub adapter. If another Code Review Agent already owns the same branch/scope it returns REVIEW ALREADY OWNED instead of starting a competing review.

Where it joins the shared engine

After the Review Target and context are established, local review is the shared engine: the same depth classification, reasoning, severity, coverage, and mechanical decision. The decision is shown as REVIEW CLEAN, CHANGES REQUIRED, or REVIEW INCOMPLETE.

Canonical references

See also

Home

Start here

Use the Skills

How reviews work

Architecture

Contribute

Background

Clone this wiki locally