Code Review

1. Determine Diff Against origin/main

Always review changes against origin/main directly. Do not use local main, git merge-base, a PR base branch, or a user-specified alternate base.

Get the CURRENT diff — never use cached results from earlier in the conversation. Include both committed and uncommitted changes (staged + unstaged):

1
2

BASE=origin/main
git diff $BASE --stat

Note: git diff origin/main (not origin/main...HEAD) diffs origin/main against the working tree, capturing committed changes, staged changes, and unstaged changes in one pass.

Show the user the file list and total count. If there are 0 changed files, report that to the user and stop — there is nothing to review. Otherwise, immediately proceed to the review agents. Do NOT wait for confirmation.

Before launching agents, build a concise review context and pass it to every agent. Show the context as a table before launching agents so assumptions are visible:

2. Spawn Parallel Review Agents

Review Philosophy

Pass these rules to every agent:

• It is OK to find nothing. A clean review is a valid outcome. Do NOT manufacture findings to justify the review. Only flag issues you are confident are real problems.
• Be opinionated and consistent. If a pattern is acceptable, don't flag it. If you flag something, commit to that position — don't suggest the opposite approach on a re-review.
• Don't flag trade-offs with no clear winner. If there are two reasonable approaches and neither is clearly better, don't flag it. The author already made a choice.
• High confidence only. Every finding must pass the bar: "I am confident this is a problem, and I can explain specifically what goes wrong if it's not fixed." Vague unease is not a finding.
• Permission-friendly reads. Avoid shell pipelines, command separators, subshells, and output filters for read-only investigation because they create extra permission prompts and block background review agents. Do not run commands like git show HEAD:path | sed -n '10,40p'. Use workspace file range reads, rg with path limits, path-scoped git diff $BASE -- <path>, or one standalone git show <rev>:<path> only when the output is acceptably small.
• Intent-aware review. Review changed code against the review context, not against the old behavior alone. Do not classify an intentional behavior change as Required merely because it differs from origin/main. A Required finding must either contradict stated intent, break an existing contract that the intent did not change, introduce a concrete bug/security issue, or leave the intended behavior unverified in a way that would likely fail.

Launch four baseline sub-agents in parallel using the Agent tool. Pass each agent origin/main as the base ref, the full list of changed files, the review context, and the review philosophy above.

When the repository is a Go project and the diff includes Go-related files (*.go, go.mod, or go.sum), also launch Agent 5 in the same batch. Do not run the Go-specific agent for non-Go diffs.

Agent 1: Security & Adversarial

Review git diff $BASE for:

• Injection — command injection, SQL injection, path traversal
• TOCTOU and race conditions — check-then-act patterns, concurrent access without synchronization
• Unvalidated input at system boundaries — user input, API parameters, external data
• Auth/authz gaps — missing permission checks, privilege escalation paths
• Secrets or credentials — hardcoded tokens, leaked keys, credentials in code or config

For EACH finding: read the actual source file and trace whether the code path is reachable in production. Discard any finding you cannot confirm with a concrete code reference.

Agent 2: Correctness & Quality

Review git diff $BASE for:

• Logic errors — off-by-one, wrong comparison, inverted conditions
• Nil/null handling — unchecked nil dereferences, missing error checks (especially unchecked errors in Go)
• Edge cases in concurrency — goroutine leaks, missing locks, channel misuse, deferred unlock ordering
• Redundant state — state that duplicates existing state, cached values that could be derived
• Production test seams — mutable function variables, package-wide settings, reset hooks, or exported knobs added only so tests can swap behavior instead of using dependency injection or a higher-scope test
• Parameter sprawl — adding new parameters instead of restructuring
• Leaky abstractions — exposing internal details, breaking existing abstraction boundaries
• Stringly-typed code — using raw strings where constants or typed values already exist in the codebase
• Test coverage and scope gaps — changed behavior, edge cases, or error paths not exercised by meaningful tests; tests that prove implementation details instead of behavior; or unit tests used where integration/e2e coverage is the right confidence boundary
• Test helper over-abstraction — helpers that hide the behavior, expected values, or assertions and make the test harder to understand than a small amount of duplication

For EACH finding: verify the claim by reading the source. Check call sites to confirm the issue is real, not hypothetical.

Agent 3: Simplification & Efficiency

Review git diff $BASE for:

• Dead code — unreachable branches, unused functions, struct fields that are never read
• Code reuse — search for existing utilities and helpers that could replace newly written code; flag duplicated functionality
• Copy-paste with variation — near-duplicate blocks that should be unified
• Unnecessary abstractions — wrapper types, indirection, or overly defensive fallbacks that mask errors
• Unnecessary work — redundant computations, repeated file reads, duplicate API calls, N+1 patterns
• Missed concurrency — independent operations run sequentially when they could be parallel
• Hot-path bloat — blocking work added to startup or per-request paths
• Unnecessary existence checks — pre-checking file/resource existence before operating (TOCTOU anti-pattern); operate directly and handle the error
• Unnecessary comments — comments explaining WHAT the code does (well-named identifiers already do that); keep only non-obvious WHY

For EACH suggestion: verify it does not break existing behavior by checking call sites and usages. Discard cosmetic-only suggestions (renames, formatting).

Agent 4: Readability & Go Idioms

Review git diff $BASE for code that is hard to read, maintain, or reason about:

• Poor factoring — functions doing multiple jobs, tangled control flow, or missing helper extraction where a small local helper would clarify behavior
• Mixed abstraction levels — high-level orchestration mixed with low-level IO, parsing, protocol, or data-structure details; low-level helpers that also make workflow or policy decisions
• Generated-code smell — repetitive pasted logic, shallow wrappers, generic names, or code that reads like it was assembled without domain intent
• Data-flow opacity — values transformed across too many steps, unclear ownership, hidden mutation, pass-through helper chains, or state threaded through unrelated code
• Control-flow complexity — deeply nested conditionals, boolean flag plumbing, early returns used inconsistently, or error paths that obscure the main path
• Naming clarity — names that hide domain meaning or force callers to inspect implementation to understand usage
• Go API readability — ambiguous (result, bool) returns outside clear comma-ok/presence checks, oversized interfaces, unnecessary pointer indirection, or cleverness where explicit Go would be clearer
• Error readability — errors that lose operation/context, wrap inconsistently, or make call sites branch on strings/booleans instead of clear errors or typed status

For EACH finding: explain the readability cost in concrete maintenance terms. Prefer small, local refactor suggestions. Discard formatting-only, gofmt-only, or personal taste comments.

Agent 5: Clean Go & Modern Go (Go diffs only)

Use the local pfleidi:clean-go skill as the source of truth: skills/pfleidi/clean-go/SKILL.md.

Review only changed Go code plus surrounding source, tests, interfaces, and call sites needed to verify findings. Apply the skill's Clean Go checks and version-gated Modern Go checks. This includes the modern-go guidance incorporated from JetBrains' use-modern-go skill: detect the relevant go.mod target version, only suggest features available for that version, and do not perform blanket modernization.

Second-Pass Coverage Sweep

After the first-pass agents complete, run a second independent review pass before synthesis. The goal is recall: catch high-confidence findings that the lens-specific agents may have missed.

Synthesize Report

After all launched agents complete:

1. Collect findings from both the first-pass agents and the second-pass coverage sweep
2. Deduplicate — merge findings from different agents that point to the same underlying issue
3. Verify — for any finding where the agent did not cite a specific file:line with evidence, read the source and confirm or discard it
4. Group by file
5. Sort by severity within each file: Critical > High > Medium > Low

Severity Definitions

• Critical — Must fix before merge. Bugs, security vulnerabilities, data loss risk, race conditions with observable impact.
• High — Should fix before merge. Missing error handling, meaningful test gaps, performance issues on hot paths.
• Medium — Worth fixing. Code reuse opportunities, unnecessary complexity, readability problems that make future changes error-prone, minor efficiency improvements.
• Low — Optional. Minor readability improvements or cosmetic suggestions.

Relevance Classification

For each finding, classify as:

• Required — The change does not work correctly without this fix in light of the review context. Bugs, missing error handling that causes failures, security vulnerabilities, race conditions, contradictions of stated intent, or missing tests for intended behavior that would likely fail. The branch should not merge without addressing these.
• Improvement — Valid finding, but the change works correctly without it. Better factoring, clearer Go APIs, using existing helpers, code reuse, unnecessary complexity, style. Worth addressing in a follow-up, not in this branch.

Autofix Eligibility

Mark each Required finding as Autofix eligible or Needs decision:

• Autofix eligible — source-backed, high confidence, minimal fix is clear, no new dependencies, no shared/public interface change, no product/design choice, no broad refactor, and the directly related verification path is clear.
• Needs decision — any Required finding that fails one of the autofix checks, including intentional behavior questions, API shape changes, cross-cutting refactors, or fixes where multiple reasonable approaches exist.

STOP and wait. The user decides what to commit.

Post-Fix

• If the user asks for changes, apply them
• If the user asks to revert specific fixes, revert ONLY those changes using surgical git checkout of the affected lines
• Do NOT commit. The user handles commits on their own terms.