tomevault-io Code Review
Review the current branch or PR against a base branch with adversarial, evidence-based scrutiny. Prefer concrete regressions over style feedback.
Default to a single pass. One reviewer reads the whole diff against the checklist in step 3; a single context keeps cross-cutting bugs (e.g. a change that is both a concurrency and a security issue) visible and findings high-signal. Reserve isolated subagents for one case: a diff too large to review in one focused pass. Partition the substantive files into a few cohesive groups (by module/directory), review each group against the full checklist — sequentially, or as a handful of parallel subagents — then merge and dedup. Never fan out by lens, and never one subagent per file — both fragment cross-cutting bugs and inflate false positives.
Inputs
- Default base:
origin/main.--base BRANCHcompares againstBRANCH. --comment [LANGUAGE]: after the report, gate posting through Posting (below) — the user approves a subset in chat and only that subset is posted viaadd-pr-comments.LANGUAGEsets comment language (default English). Without--comment, the report (step 6) is the final artifact and nothing is posted.
Workflow
Pin the comparison. Set
BASE_BRANCHfrom--baseororigin/main, then:HEAD_SHA=$(git rev-parse HEAD) MERGE_BASE=$(git merge-base "$BASE_BRANCH" "$HEAD_SHA")Review
"$MERGE_BASE".."$HEAD_SHA"for the entire pass.Inventory the diff: changed files, shortstat, added/deleted files, diff body. Ignore generated files, vendored code, lockfiles, snapshots, and docs-only changes unless they affect runtime, build, or security.
Read the whole diff against this checklist — or, if it is too large for one focused pass, partition it as described in the intro.
correctnessalways applies; the rest are cues — weight attention to what the diff actually touches. Gather evidence first (cited ranges, prior vs current behavior, touched callers, reachable inputs), then draft a finding only from evidence: title, severity, confidence,file:line, failure mode, fix.Lens Look for correctnesslogic, null handling, contracts, stale callers, data corruption, migrations, cache staleness, unreachable code securityauth/authz, injection, unsafe deserialization, SSRF, path traversal, tenant or PII leaks concurrencynon-atomic updates, lock ordering, cancellation hazards, retry interactions, double-submit/double-process architectureboundary breaks, dependency direction, wrong-layer abstractions, cross-module coupling maintainabilitybrittle abstractions, unclear invariants, accidental complexity, obvious simplification not taken testingcoverage gaps for changed behavior, weak assertions, flakiness, fixture pollution performancequery shape, N+1s, hot-path allocations, nested loops over user data, missing or wrong caching Apply the bar. Self-critique each candidate from the PR author's perspective and keep only what the author would clearly fix. Returning zero findings is correct — if nothing clears the bar, say so; never pad the report. Move plausible-but-unverified concerns to residual risks.
Validate every surviving finding against the current code and diff; drop anything the cited range does not support. Dedup overlapping findings, keeping the strongest severity/confidence.
Report in this order:
- Review range:
<merge-base>..<HEAD>resolved to short SHAs - Verdict: exactly one of
ready to approve,ready after fixes, ornot ready— one line, naming the blockers if any - Findings: title,
SEV/CONF,file:line, failure mode, fix - Cross-cutting risks, if any
- Residual risks: plausible-but-unverified concerns, if any
- Review range:
If
--commentis set, gate posting through Posting below — the only path that writes to GitHub, and only after explicit user approval.
Posting (--comment)
Posting is the only irreversible step — never invoke add-pr-comments or any gh write until the user approves the final set.
- List the surviving findings with stable IDs (
F1,F2, …). Ask the user to reply keep / drop / dive per finding — e.g. "drop F2, dive F4: check the lock at L138, keep the rest." - For each dive, re-investigate the finding inline against the cited code (with surrounding context), its lens, and the user's hint. Report the refined finding — or that it cannot be substantiated — then re-confirm keep/drop on it.
- Show the final to-be-posted set and wait for an explicit go-ahead.
- Re-check
git rev-parse HEAD; if it moved since the review, warn that line anchors may have shifted and confirm before continuing. Hand the kept set +LANGUAGE(default English) toadd-pr-comments. - If nothing is kept, post nothing and say so.
Follow-ups
After the report, answer user follow-ups conversationally:
- Clarification ("why is F2 high severity?"): answer from the cited evidence; if the question is outside the diff, say so.
- Deep dive ("F4 looks shallow — did you check the lock at line 138?"): re-investigate the finding inline against the cited code (with surrounding context), its lens, and the user's hint; report the refined finding.
- More lenses ("focus on security too"): re-read the same merge-base/HEAD diff with that lens weighted and report.
Severity
critical: exploitable security issue, auth bypass, data loss, corruption, severe outagehigh: likely production failure or serious regressionmedium: real bug under a plausible edge caselow: non-trivial issue worth fixing, not a blocker
A blocker is a finding that makes the change unsafe to merge as-is — critical or high by default, a medium only when its edge case is plausible in practice; low is never a blocker.
Confidence
high: directly supported by cited codemedium: strong evidence with one assumptionlow: plausible but speculative — prefer residual risk over a low-confidence finding
Avoid
- Pre-existing issues this change neither introduces nor worsens
- Style nits, formatting, subjective preferences, or linter-level issues
- "Check / verify / ensure / confirm X" hedges, or any comment that does not name a concrete failure mode
- Missing tests without a concrete regression risk
- Claims that cannot be verified from the diff and current code
Source: tkxkd0159/agent-plugins — distributed by TomeVault.