Automated code quality review with language-aware analysis, pre-commit verification, and multi-specialist deep review

version
0.0.18
GitHub stars
123

Install

/plugin install code-review@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Skills 5

Classify Review Comments

Classify GitHub pull request review comments into severity and topic categories. Works with a single comment (text), a GitHub comment URL, or an entire PR (classifies all comments).

This enables tracking review feedback patterns: what kinds of issues reviewers catch, how severe they are, and where AI-generated code needs the most improvement.

Labels

Read the labels file before classifying any comments:

config.json (in the same directory as this skill)

The labels file defines the exact set of valid values for severity and topic. You MUST select from these values — do not invent new labels. Each label includes a description and signal words or examples to guide your selection.

Classification rule: For each comment, find the single best-matching severity and single best-matching topic from the labels file. Match based on the label's description, signals/examples, and the comment content. Use unclassified only when no other label fits.

Input Modes

1. Single Comment (text)

Classify a comment provided directly as text.

Input: The raw comment body. Output: A single classification object.

2. Comment URL

Fetch a specific comment by its GitHub URL and classify it.

URL formats supported:

  • https://github.com/{owner}/{repo}/pull/{number}#issuecomment-{id}
  • https://github.com/{owner}/{repo}/pull/{number}#discussion_r{id}
  • https://github.com/{owner}/{repo}/pull/{number}#pullrequestreview-{id}

Fetch with:

# Issue comment
gh api repos/{owner}/{repo}/issues/comments/{id} --jq '{author: .user.login, body: .body}'

# Review comment (discussion)
gh api repos/{owner}/{repo}/pulls/comments/{id} --jq '{author: .user.login, body: .body}'

# Review body comment
gh api repos/{owner}/{repo}/pulls/{number}/reviews/{id} --jq '{author: .user.login, body: .body}'

3. Full PR

Fetch all comments on a PR, filter out noise, and classify each one.

URL format: https://github.com/{owner}/{repo}/pull/{number}

Fetch with:

# Issue-level conversation comments
gh api repos/{owner}/{repo}/issues/{number}/comments --paginate --jq '.[] | {id: .id, author: .user.login, body: .body}'

# Inline review comments
gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate --jq '.[] | {id: .id, author: .user.login, body: .body}'

# Review body comments (approvals, rejections, general review summaries)
gh api repos/{owner}/{repo}/pulls/{number}/reviews --paginate --jq '.[] | select(.body != null and .body != "") | {id: .id, author: .user.login, body: .body}'

Before classifying, filter out noise comments (these carry no review signal):

  • Pure slash commands: body starts with / followed by a command word (e.g., /lgtm, /test e2e-aws, /approve, /retest, /cc)
  • CI bot notifications: authors like openshift-ci-robot, openshift-ci[bot], cwbotbot, or any *[bot] author not listed in the allowed_bots section of config.json
  • Comments matching any pattern in the noise_patterns section of config.json
  • Auto-CC commands: /auto-cc

Do classify comments from:

  • Human reviewers (all comments, including those directing bots)
  • Any bot listed in allowed_bots in config.json (classify their substantive review comments — code issues, suggestions, questions)

Classification Approach

For each comment:

  1. Read config.json to load the valid severity and topic values
  2. Scan the comment body for signal words and patterns that match label descriptions
  3. Select exactly one severity — match the comment's urgency/tone to the severity descriptions and signals
  4. Select exactly one topic — match the comment's subject matter to the topic descriptions and examples
  5. Score confidence using the rubric below
  6. When ambiguous, prefer the more specific label over unclassified
  7. When a comment spans multiple topics, pick the primary one — what is the reviewer's main concern?

Confidence Scoring Rubric

Each classification includes a confidence score (0.00–1.00) indicating how certain the classification is. Accumulate the score from these signals:

SignalWeightCriteria
Signal word match+0.25Comment contains signal words/phrases from config.json for the chosen severity or topic label
Unambiguous category+0.25Comment clearly fits one severity and one topic with no viable alternatives
Example pattern match+0.25Comment closely matches a real-world example in this skill or in config.json
Context reinforcement+0.15Multiple independent indicators point to the same classification (e.g., tone + keywords + structure all agree)
Single viable label+0.10No other severity or topic label is a reasonable alternative

Maximum score is 1.00. When multiple signals apply, sum them and cap at 1.00.

Interpretation:

  • >= 0.95 — High confidence: classification can be auto-applied for low-risk labels
  • 0.80–0.94 — Moderate confidence: human confirmation recommended
  • < 0.80 — Low confidence: manual classification required

Additional classification rules:

  • Slash commands mixed with text — if a comment has substantive text before a slash command (e.g., "good analysis\n/override ci/prow/e2e"), classify based on the substantive text, not the slash command
  • Comments directed at bots/AI — classify by the underlying problem, not the fact that the recipient is a bot. "Fix the unit tests" is about test failures (test_gap), "rebase the PR" is a CI/process issue (ci), "push the changes" is a process failure (process). The topic should answer "what went wrong?" not "who is being told to fix it?"

Output Format

Single comment

{
  "severity": "<value from config.json severity list>",
  "topic": "<value from config.json topic list>",
  "confidence": 0.95,
  "rationale": "Brief one-line explanation of why this classification was chosen"
}

Full PR

{
  "pr": "https://github.com/openshift/hypershift/pull/7620",
  "total_comments": 15,
  "classified": 5,
  "filtered_noise": 10,
  "comments": [
    {
      "id": 2871360513,
      "author": "jparrill",
      "body_preview": "small nit: I would move the vars...",
      "severity": "<value from config.json>",
      "topic": "<value from config.json>",
      "confidence": 0.95,
      "rationale": "Reviewer suggests moving variable declarations for consistency"
    }
  ],
  "summary": {
    "by_severity": {"nitpick": 1, "suggestion": 1, "required_change": 2, "question": 1},
    "by_topic": {"style": 1, "api_design": 1, "logic_bug": 2, "test_gap": 1},
    "by_confidence": {"high": 3, "moderate": 1, "low": 1}
  }
}

Real-World Examples

These are from actual PRs in openshift/hypershift:

Comment: "small nit: I would move the vars key, log and cloudName to var ( section just to be consistent."

{"severity": "nitpick", "topic": "style", "confidence": 1.00, "rationale": "Reviewer suggests grouping variables for consistency — cosmetic, not functional"}

Comment: "Why not use NewARMClientOptions here for the clientOptions?"

{"severity": "question", "topic": "api_design", "confidence": 0.90, "rationale": "Reviewer asks about API choice for client options construction"}

Comment: "This will panic if items is nil — needs a nil check before the loop"

{"severity": "required_change", "topic": "logic_bug", "confidence": 1.00, "rationale": "Nil pointer dereference would cause runtime panic"}

Comment: "failing during hypershift install\n\nClusterRoleBinding is invalid: roleRef.kind: Unsupported value\n"

{"severity": "required_change", "topic": "logic_bug", "confidence": 0.90, "rationale": "Installation fails due to missing required roleRef fields"}

Comment: "hypershift-jira-solve-ci - the unit test job is failing and needs fixed"

{"severity": "required_change", "topic": "test_gap", "confidence": 0.90, "rationale": "Unit tests are failing — the bot made code changes without ensuring tests pass"}

Comment: "hypershift-jira-solve-ci - rebase the PR to fix the konflux issues"

{"severity": "suggestion", "topic": "ci", "confidence": 0.85, "rationale": "PR needs rebasing to resolve CI pipeline issues — classify by the problem (CI), not the recipient (bot)"}

Comment: "hypershift-jira-solve-ci - this still needs fixed since the code did not get pushed"

{"severity": "required_change", "topic": "process", "confidence": 0.85, "rationale": "Code changes were not committed/pushed — a process failure, not a code issue"}

Comment: "e2e-aws-4-21 failed on Teardown but due to uncleaned cloud resources, not VPC endpoint blocking the finalizer\n/override ci/prow/e2e-aws-4-21"

{"severity": "suggestion", "topic": "ci", "confidence": 0.75, "rationale": "Reviewer explains CI failure root cause and overrides — substantive analysis before the slash command"}

Comment: "Oh no that's ok. I missed that part. No changes requested."

{"severity": "unclassified", "topic": "approval", "confidence": 0.70, "rationale": "Reviewer withdrawing their earlier question — acknowledgment"}

Comment: "dup of https://github.com/openshift/hypershift/pull/7727"

{"severity": "unclassified", "topic": "process", "confidence": 0.90, "rationale": "Marking PR as duplicate of another — process meta-comment"}

Comment: "The root cause of the CI failure in this PR has been identified. The fix in rejectVpcEndpointConnections doesn't work because of a case mismatch between AWS API responses and SDK v2 enum constants."

{"severity": "required_change", "topic": "logic_bug", "confidence": 1.00, "rationale": "Detailed root cause analysis identifying a case mismatch bug"}

Comment: "This controller is doing too much — the reconciler should delegate VPC cleanup to a separate controller instead of inlining it"

{"severity": "suggestion", "topic": "architecture_design", "confidence": 0.90, "rationale": "Reviewer identifies a separation-of-concerns issue at the controller level"}

Comment: "The service account token is being logged in plain text here — this needs to be redacted"

{"severity": "required_change", "topic": "security", "confidence": 1.00, "rationale": "Sensitive credentials exposed in log output — security vulnerability"}

CodeRabbit issue flagged (starting with _Potential issue_ | _Critical_):

{"severity": "required_change", "topic": "logic_bug", "confidence": 0.85, "rationale": "CodeRabbit identified a critical code issue requiring attention"}

Deep Review — Multi-Specialist Panel Review with Reproducers

Review a branch's changes with parallel specialist subagent reviewers, each examining the code through a different lens. Verify every bug finding with a runtime reproducer. Optionally post to GitHub/GitLab as a PENDING review.

No PR/MR is required — the review works on any branch with commits ahead of its base.

Two execution modes:

  • Parallel (default): Each specialist runs as a dedicated sub-agent concurrently. Thorough but expensive — each sub-agent independently derives its own view of the codebase.
  • Serial (--serial): All specialists run inline in the main agent, one after another. Significantly cheaper because the codebase context is derived once and shared across all specialists. Trade-off: reviews run sequentially, and later specialists can see prior specialists' findings (which may bias their analysis).

Arguments

/code-review:deep-review [flags] [pr-url-or-number]
ArgumentDescription
--serialRun all specialists inline instead of as parallel sub-agents
--commentPost the verdict as a PR comment after review. Requires a PR identifier
--coderabbitInclude CodeRabbit as an external reviewer
--codexInclude OpenAI Codex as an external reviewer
-reviewerExclude a specialist (e.g., -writer,-qa). All enabled by default
pr identifierGitHub/GitLab PR URL or bare PR number. Optional

Examples:

  • /code-review:deep-review — all reviewers, review current branch
  • /code-review:deep-review --serial — cheaper serial mode
  • /code-review:deep-review -qa,-writer — skip QA and Technical Writer
  • /code-review:deep-review --comment 42 — review PR #42, post verdict as comment
  • /code-review:deep-review --coderabbit https://github.com/org/repo/pull/42
  • /code-review:deep-review https://gitlab.com/org/repo/-/merge_requests/7

Specialist Panel

All are enabled unless excluded with -:

SpecialistLensReproducer?
bugsFunctional bugs: missing calls, wrong logic, unhandled edge casesYes — mandatory
adversarialBreak the code: bad inputs, race conditions, boundary valuesYes — mandatory
securityVulnerabilities, credential handling, dependency trust, supply chain integrityWhen claiming a concrete exploit
architectureStructural patterns, SOLID, cross-file impact, module boundariesNo
consistencyDuplicate helpers, convention drift, style match with existing codeNo
qaTest coverage gaps, missing edge-case tests, concrete test suggestionsNo
writerDocumentation accuracy, staleness, consistency with code changesNo

Routing Topology

  bugs  adversarial  security  architecture  consistency  qa  writer
    \_______|__________|__________|___________|___________|____|
                                 |
                           [reproduce]  ← bug/security findings only
                                 |
                                 v
                           panel-arbiter
                         (final call)
  • Specialists raise findings independently — no implicit consensus. Each runs as a separate sub-agent and cannot see the others' output.
  • Reproducer agents verify bug/security claims before arbitration.
  • Panel Arbiter synthesizes after all specialists and reproducers complete.

Procedure

Phase 1 — Setup

Step 1.1: Parse arguments

Split the argument string on whitespace. Flags (--serial, --comment, --coderabbit, --codex) set modes. Tokens like -writer,-qa exclude those specialists (validate against the roster; unknown names warned and ignored). A PR URL or bare integer is the PR identifier (for bare integers, detect platform from git remote). Error if: all specialists excluded, --comment without PR identifier, or multiple PR identifiers.

Step 1.2: Check out the PR and determine base ref

If a PR/MR URL or number was provided, parse it before checkout. Do not pass a raw URL as an ID:

  1. GitHub URL (github.com/.../pull/N): set PLATFORM=github, OWNER, REPO, PR_NUMBER=N
  2. GitLab URL (gitlab.com/.../-/merge_requests/N): set PLATFORM=gitlab, PROJECT (group/subgroup/repo path), MR_IID=N. Prefer OWNER/REPO only when the project path has exactly two segments
  3. Bare integer: detect platform from git remote -v (GitHub → gh, GitLab → glab), then set PR_NUMBER or MR_IID. Derive OWNER/REPO or PROJECT from the matching remote URL

Check out locally (always quote shell arguments):

GitHub:

gh pr checkout "$PR_NUMBER" --repo "$OWNER/$REPO"

GitLab:

glab mr checkout "$MR_IID" --repo "$PROJECT"

If glab accepts the full MR URL as a single argument, that is also fine — but never treat the URL string as $MR_IID for flags that expect a numeric IID alone.

Hard failure on inaccessible PR/MR: If a PR/MR identifier was provided and checkout or metadata fetch fails (wrong URL, private repo, missing permissions, 404/403), error and exit immediately. Do not fall back to reviewing the current local branch — that silently reviews the wrong code.

Determine the base branch and remote:

  1. If a PR/MR is known, use its base ref (gh pr view --json baseRefName or glab mr view --output json)
  2. Discover remotes with git remote -v (do not hardcode origin/upstream). Prefer the remote whose fetch URL matches the PR/MR host and project; otherwise use the remote tracked by the current branch (git branch -vv), then any remaining remote
  3. If a PR/MR is known, probe its target branch first on the matching remote and use it as $BASE_REMOTE/$BASE_BRANCH. Only fall back to probing main then master (git ls-remote --heads "$REMOTE" main master) when no target branch was provided or the target branch was not found

Fetch and compute the merge base:

git fetch "$BASE_REMOTE" "$BASE_BRANCH"
MERGE_BASE=$(git merge-base "$BASE_REMOTE/$BASE_BRANCH" HEAD)

If no base ref can be determined, error and exit.

Step 1.3: Verify there are changes

Check that the branch has commits ahead of the base. If there are no changes, stop: "No changes found between HEAD and the base branch."

If a PR/MR exists, also fetch its description for context.

Step 1.4: Detect prior reviews (PR only)

When reviewing a PR/MR, check for previous panel review comments:

GitHub:

gh pr view "$PR_NUMBER" --json comments --jq \
  '.comments[] | select(.body | contains("Generated by /deep-review") or contains("Generated by /code-review:deep-review")) | {createdAt, body}'

GitLab:

glab mr note list "$MR_IID" --repo "$PROJECT" 2>/dev/null \
  | rg -n "Generated by /(code-review:)?deep-review" || true

If prior panel reviews exist, extract their findings and pass them to all specialists and the arbiter as context. Specialists should:

  • Note which prior findings have been addressed by subsequent commits
  • Flag prior findings that remain unresolved
  • Avoid re-raising issues that were already noted and resolved
  • Call out any regressions — issues that were fixed but reappeared

Phase 2 — Dispatch Specialists

Each specialist has its own prompt in references/specialists/:

SpecialistPrompt
bugsreferences/specialists/bugs.md
adversarialreferences/specialists/adversarial.md
securityreferences/specialists/security.md
architecturereferences/specialists/architecture.md
consistencyreferences/specialists/consistency.md
qareferences/specialists/qa.md
writerreferences/specialists/writer.md

Append the findings JSON schema to each specialist prompt:

[
  {
    "file": "src/example.py",
    "line": 42,
    "severity": "BLOCKING",
    "title": "Short title",
    "body": "Description of the issue",
    "suggestion": "Recommended action or null",
    "reproducer_needed": true
  }
]

Severity values: BLOCKING | SUGGESTION | NOTE

If no issues found, return an empty array and state what was checked.

Parallel Mode (default)

Launch all enabled specialist sub-agents in a single message so they run concurrently, using the Agent tool with run_in_background: true.

Resolve specialist prompts from the skill directory (repository root relative): plugins/code-review/skills/deep-review/references/specialists/{specialist}.md. Do not use a bare references/specialists/... path — agents may not share the skill's working directory.

Each sub-agent gets:

  • The prompt: "You are a {specialist}. Read plugins/code-review/skills/deep-review/references/specialists/{specialist}.md for your review instructions."
  • The merge base ref
  • The PR number or branch name being reviewed
  • Any prior review findings (if detected in Step 1.4)
  • The findings JSON schema above

Sub-agents have full read access to the locally checked-out codebase. They explore the code on their own — read files, grep, run git commands, etc.

Sub-agents MUST NOT modify any files, and MUST NOT run any remote-write git commands (git push, force-push variants, push to protected branches, or pushes to any remote). They are read-only reviewers.

Use subagent_type: "general-purpose". Do NOT set the model parameter.

Serial Mode (--serial)

Run all enabled specialists inline in the main agent, one after another. Do not launch sub-agents for specialist dispatch. (Phase 4 reproducer sub-agents are still launched even in serial mode — the no-sub-agent constraint applies only to specialists.)

Then for each specialist in roster order, state the specialist name as a heading, read plugins/code-review/skills/deep-review/references/specialists/{specialist}.md for review instructions, review through that lens, and produce findings in the same JSON format. Context from earlier specialists' file reads and findings carries over automatically.

Do NOT modify any files, and do NOT push to any remote. Serial mode is read-only, same as parallel.

External Reviewers

If external reviewers were requested, launch them in parallel with (or before, in serial mode) the specialist dispatch.

CodeRabbit (--coderabbit):

timeout 300 coderabbit review --agent --base "$MERGE_BASE" 2>&1

Codex (--codex):

timeout 300 codex review 2>&1

External reviewer output is captured as-is and included in the arbiter's synthesis input as a peer specialist. If a command fails (non-zero exit, tool not found, timeout), record the error and continue — never block the panel on an external tool failure.

Phase 3 — Completeness Gate

After all sub-agents and external reviewers return, verify all enabled specialists produced findings (or an explicit "no issues" with what was checked). A valid empty JSON array [] with an explanation of what was checked is success — do not retry it. If any specialist returned an error or a missing/malformed result, re-dispatch it once. If the retry also fails, record the failure and proceed.

External reviewer failures are non-blocking — note the error and continue.

Phase 4 — Reproduce

For every BLOCKING finding with reproducer_needed: true, launch a reproducer subagent (up to 5 in parallel). See references/reproducer-prompt.md for the prompt template and result processing rules.

Phase 5 — Panel Arbiter

Perform synthesis directly in the main agent (not a sub-agent).

  1. Deduplicate — merge duplicates, keep strongest reproducer
  2. Filter noise — remove false positives, style nitpicks, speculative findings, and issues already addressed in the branch
  3. Resolve conflicts — corroboration strengthens; adversarial concerns are blocking unless concretely refuted
  4. Assign disposition — APPROVE (no BLOCKING), REQUEST_CHANGES (BLOCKING findings), or NEEDS_DISCUSSION (needs author input). Biases: security over ergonomics, consistency over elegance, reproduced bugs are always BLOCKING, do not manufacture findings
  5. Prioritize — reproduced security bugs > reproduced functional bugs > unreproduced > architecture > style/docs
  6. Emit verdict — use collapsible <details> blocks for specialist findings (each specialist collapsed with severity counts). Sections: Disposition, Specialist Findings, Panel Synthesis, Required Actions, Optional Follow-ups, Stats. Footer: <sub>Generated by [/code-review:deep-review](https://github.com/openshift-eng/ai-helpers/tree/main/plugins/code-review/skills/deep-review)</sub>. Include collapsible reproducer details for confirmed BLOCKING bugs.

Phase 6 — Post to PR (Optional)

When --comment was passed, follow references/pr-posting.md to post the verdict to the PR and optionally create inline review comments. $OWNER, $REPO, $PR_NUMBER / $PROJECT, $MR_IID must already be set from Step 1.2.

Quality Gates

A change passes when: no unresolved functional bugs, no unrefuted adversarial scenarios, no unmitigated vulnerabilities or supply chain risks, sound architecture, no duplicate helpers, adequate test coverage, documentation consistent with changes, and the panel arbiter has ratified the disposition.

Error Handling

  • gh/glab not authenticated: Review can still run on a locally checked-out branch.
  • No PR exists: Skip Phase 6; the verdict is the deliverable.
  • External tool not installed/timeout: Skip, warn, continue.
  • Subagent timeout: Report which specialist timed out, continue.
  • No changes: Stop — "No changes found."
  • Review creation fails (422): Delete only comment/review IDs created by the current attempt, then retry. Never delete existing reviewer comments from other runs or authors.

Guardrails

  • Never submit a PR review without explicit user confirmation.
  • Never use "event" in the initial review creation payload.
  • Review agents MUST NOT modify any files in the working tree.
  • Never git push, force-push, or push to protected branches (main/master) or any other remote. Do not assume remote names — discover them with git remote -v when needed for reads.
  • Reproducers run in /tmp. Do not push reproducer files.
  • Do not run destructive operations in reproducers.
  • Cap at 30 inline PR comments. Overflow goes to the review body.

Go Language Review

This skill provides Go-specific guidance for code quality reviews. The pre-commit-review skill loads it when --language go is specified or when .go files are detected among the changed files.

When to Use This Skill

Use this skill when reviewing Go source code. Its sections are referenced during the unit test coverage, idiomatic code, and build verification review steps.

Test Conventions

  • Table-driven tests: Prefer table-driven tests for functions with multiple input/output combinations
  • Subtests: Use t.Run() for subtests to provide clear test case identification
  • Parallel tests: Use t.Parallel() at the top of test functions and subtests where tests are independent
  • Race detection: Tests must be compatible with the -race flag — avoid shared mutable state between parallel tests
  • File co-location: Test files must be co-located with source files using the _test.go suffix
  • Test helpers: Use t.Helper() in test helper functions so failure messages report the caller's line number
  • Behavior-focused: Test names should describe behavior, not implementation. Test both success and error paths

Idiomatic Go

Follow the conventions in Effective Go and the Go Code Review Comments wiki. Key reminders:

  • Formatting: All code must be formatted with gofmt. Unformatted code is a blocking issue
  • Naming: Use MixedCaps / mixedCaps. Avoid stuttering (http.Server not http.HTTPServer). Acronyms are all caps (URL, HTTP, ID)
  • Error handling: Check every error. Wrap with fmt.Errorf("context: %w", err) to preserve the chain for errors.Is() / errors.As()
  • Interfaces: Keep interfaces small. Accept interfaces, return concrete types
  • Early returns: Handle error cases first; keep the happy path at the lowest indentation level
  • Context: Pass context.Context as the first parameter to functions that perform I/O or may be long-running

Build Commands

Use the following commands in priority order during build verification:

  1. Tests: make test if a Makefile with a test target exists; otherwise go test -race ./...
  2. Verification: make verify if available; otherwise go vet ./...
  3. Build: make build if available; otherwise go build ./...

HyperShift Project Profile

This profile provides project-specific review guidance for the openshift/hypershift repository. Instead of embedding domain knowledge, it points to the agents and skills already defined in the hypershift repo's .claude/ directory.

When to Use This Skill

Use this skill when --profile hypershift is specified.

Agents

The hypershift repository maintains its own Claude agents at .claude/agents/ that contain deep domain expertise (API, cloud providers, control plane, data plane, architecture). During review:

  1. If inside a local hypershift checkout: Read the agent definitions from .claude/agents/ in the repo root. Pick the agents relevant to the changed files based on each agent's own description, and launch them as sub-agents.
  2. If not in a hypershift checkout: Fetch the agent definitions using gh api repos/openshift/hypershift/contents/.claude/agents?ref=main (or the GitHub contents API) and use them.
  3. Use all HyperShift SME agents including (control-plane-sme, data-plane-sme, api-sme, cloud-provider-sme and hcp-architect-sme) to review branch changes or a given PR, questioning the approach and whether it solves the underlying problem.

The repo also has skills at .claude/skills/ (debugging, effective Go, git commit format, CLI conventions). Apply any that are relevant to the changed files.

For test naming and structure conventions, read TESTING.md and the Code Conventions section of DEVELOPMENT.md in the repo root — these are the authoritative sources for test requirements.

Build Commands

  • make test — unit tests with race detection
  • make verify — full verification suite (code generation, formatting, vetting, linting, tests)
  • make api — required if any files in api/ were modified; regenerates deepcopy, clients, informers, and listers

API Type Changes

If any files in the api/ directory were modified, verify that make api has been run and the generated files are included in the diff. Missing generated files are a blocking issue.

Name

code-review:pre-commit-review

Synopsis

/code-review:pre-commit-review [--language <lang>] [--profile <name>] [--skip-build] [--skip-tests]

Purpose

Review the current staged and unstaged changes before committing. Assess test coverage, idiomatic code, duplication, design, and build verification. Review only the current diff; do not report pre-existing issues in unchanged code.

The same-named skill replaces the former plugin command, so the /code-review:pre-commit-review invocation remains available in Claude Code. Install the plugin through APM to expose this skill to OpenCode and other supported clients.

Workflow

1. Resolve options and review guidance

Read options from the skill invocation or the user's request:

OptionBehavior
--language <lang>Apply language-specific review guidance. If omitted, detect from changed-file extensions.
--profile <name>Apply project-specific conventions and checks.
--skip-buildSkip build verification and report it as skipped.
--skip-testsSkip unit-test coverage review and report it as skipped.

Detect the primary language from changed-file extensions: .go → Go, .py → Python, .rs → Rust, .ts/.tsx → TypeScript, and .java → Java. If files are mixed or the language has no guidance, continue with a general review.

Load optional guidance from sibling skill directories, relative to this SKILL.md:

  • Language: ../<language>-code-review/SKILL.md (currently available: ../go-code-review/SKILL.md).
  • Profile: ../<name>-code-review/SKILL.md (for example, ../hypershift-code-review/SKILL.md).

If requested guidance is absent, say so and continue without it. Give loaded guidance to each relevant review pass.

Completion criterion: all supplied options are accounted for, and each available language/profile guide has been loaded before reviewing.

2. Establish the diff

Collect and deduplicate changed paths from both git diff --name-only and git diff --cached --name-only. Categorize them as source, tests, configuration, or documentation. If the diff is empty, report that and stop. If no source files changed, narrow the review accordingly.

Completion criterion: the complete staged and unstaged file list is recorded, with no unchanged files added to scope.

3. Review the changes

Run these independent review passes:

  1. Test coverage — unless --skip-tests was supplied, check for tests covering changed behavior, new public functions, edge cases, and error paths. A missing test for a new public function with non-trivial logic is blocking. Apply language and profile test conventions.
  2. Idiomatic code — apply language guidance when available; otherwise assess error handling, naming, clarity, and complexity. Follow relevant project guidance.
  3. DRY — find duplication, repeated patterns, copy-paste code, and values that should be named constants. Apply profile guidance about shared project utilities.
  4. Design — assess responsibilities, extensibility, interface contracts, interface size, and dependency direction in proportion to the change.
  5. Profile-specific review — apply extra checks and reviewer perspectives named by the profile.

Keep each pass independent until findings are collected. When the host supports agent delegation, delegate independent passes concurrently and provide each reviewer with the changed-file list and relevant guidance. Otherwise, perform the passes sequentially in this session. If the profile names specialist reviewers, use the host's available delegation mechanism; without delegation, apply each specialist perspective as a separate pass. Provide the full diff and available PR or issue context to profile-specific reviewers.

Completion criterion: every applicable pass has examined every in-scope change, and skipped passes are recorded with the supplied option that skipped them.

4. Verify the build

Unless --skip-build was supplied, run the most specific available build/verification command in this order:

  1. Profile guidance.
  2. Language guidance.
  3. Project detection: make build (or the documented default make) when a Makefile is present; go build ./... for Go; cargo build for Rust; npm run build or yarn build for JavaScript/TypeScript; python -m py_compile on changed files for Python.

Run this alongside review passes when the host supports concurrent work. Record the command and result. On failure, include the relevant output and mark the overall review as FAIL. If explicitly skipped, report it as skipped; do not imply that the build was verified.

Completion criterion: build verification is recorded as passed, failed, or explicitly skipped; no result is implied.

5. Report findings

Return a structured report with:

  1. Files reviewed, categorized by type.
  2. Unit-test coverage findings, or that the pass was skipped.
  3. Idiomatic code findings, naming the language when applicable.
  4. DRY and design findings.
  5. Build command and result.
  6. Profile-specific findings, if applicable.
  7. Overall verdict: PASS, FAIL, or PASS WITH RECOMMENDATIONS.
  8. Required actions (blocking) and recommended improvements (non-blocking).

Make findings specific and actionable, with file:line references where possible. Match review depth to change risk. Offer to fix straightforward issues rather than silently expanding the review into implementation.

Completion criterion: every finding is tied to changed code, has an actionable recommendation, and the verdict reflects all review and build results.

Examples

/code-review:pre-commit-review
/code-review:pre-commit-review --language go --profile hypershift
/code-review:pre-commit-review --skip-build
/code-review:pre-commit-review --language python --skip-tests

Commands 1

Name

code-review:pr

Synopsis

/code-review:pr <pr-url-or-number> [--language <lang>] [--profile <name>] [--skip-build] [--skip-tests]

Description

The code-review:pr command performs a comprehensive code quality review of the changes in a GitHub Pull Request. It analyzes unit test coverage, idiomatic code patterns, DRY compliance, SOLID principles, and build verification.

The command supports two layers of customization:

  1. Language skills (--language <lang>): Load language-specific guidance for idiomatic code review, test conventions, and build commands. Currently shipped: go. Planned: python, rust, typescript, java. If not specified, the language is auto-detected from changed file extensions.

  2. Profile skills (--profile <name>): Load project-specific guidance that layers on top of language checks. Profiles add project conventions, shared utilities, build targets, and additional review criteria. Profiles reference the project's own agents and skills rather than embedding them.

The two layers compose: --language go --profile hypershift applies both Go idioms and HyperShift project conventions.

Implementation

Step 0 — Parse Arguments & Load Skills

  • Parse $ARGUMENTS for the following:
    • PR identifier (required, first positional argument): Either a full GitHub PR URL (e.g., https://github.com/owner/repo/pull/123) or a PR number (e.g., 123). When only a number is provided, the current repository's remote is used.
    • --language <lang>: Language skill to load (e.g., go, python, rust, typescript, java)
    • --profile <name>: Project profile skill to load (e.g., hypershift)
    • --skip-build: Skip build verification step
    • --skip-tests: Skip unit test coverage review step
  • If no PR identifier is provided, ask the user for one.
  • If --language is not specified, auto-detect the primary language from the file extensions of changed files (determined in Step 1):
    • .go -> go
    • .py -> python
    • .rs -> rust
    • .ts, .tsx -> typescript
    • .java -> java
    • If mixed or unrecognized, proceed without a language skill
  • Check for the language skill file at skills/lang-<lang>/SKILL.md relative to the plugin root directory. If the skill exists, read it and store its content for use by sub-agents. If it does not exist, inform the user and proceed with a generic review.
  • If --profile is specified, check for the profile skill file at skills/profile-<name>/SKILL.md relative to the plugin root directory. If the skill exists, read it and store its content for use by sub-agents. If it does not exist, warn the user and proceed without profile-specific checks.

Step 1 — Fetch PR Diff & Identify Changed Files

  • Use gh pr diff <pr-identifier> to fetch the full PR diff.
  • Use gh pr view <pr-identifier> --json files --jq '.files[].path' to get the list of changed files.
  • Also fetch the PR metadata for context: gh pr view <pr-identifier> --json title,body,baseRefName,headRefName,author.
  • Focus the review exclusively on changed files. Do not review unchanged files.
  • Categorize files by type: source code, test files, configuration, documentation.
  • If no source code files are changed (e.g., only docs or config), note this and adjust the review scope accordingly.
  • Store the changed file list and the full diff — they are passed to every sub-agent in the next step.

Important: The review is performed against the PR diff, not the local working tree. Sub-agents should analyze the diff content to understand what changed. However, they may read local files for additional context (e.g., to understand how a changed function fits into the broader codebase), as long as the local checkout is on the PR branch or a compatible state.

Step 2 — Launch Parallel Review Sub-Agents

After identifying changed files, launch the following reviews concurrently. Launch ALL sub-agents in parallel (single message with multiple Task tool calls) for maximum speed. Each sub-agent should be given subagent_type: "general-purpose". Do NOT set the model parameter — let sub-agents inherit the parent model, as these analysis tasks require a capable model. Pass each sub-agent the list of changed files, the full PR diff, the loaded language skill content (if any), and the loaded profile skill content (if any) in its prompt. Every sub-agent must return findings as structured text.

Sub-agent: Unit Test Coverage

Skip if --skip-tests is specified.

  • For each new or modified source file, check if a corresponding test file exists.
  • For each new exported/public function with non-trivial logic, verify that tests exist.
  • Evaluate test quality: Are tests testing meaningful behavior or just achieving coverage?
  • Check for edge cases, error paths, and boundary conditions in tests.
  • If a language skill is loaded, apply its test conventions (e.g., Go: table-driven tests, t.Run(), t.Parallel()).
  • If a profile is loaded, apply its additional test conventions.
Sub-agent: Idiomatic Code
  • If a language skill is loaded, apply its idiomatic code guidance to the changed files.
  • If no language skill is loaded, perform a general review: error handling, naming, clarity, complexity.
  • If a profile is loaded, follow the profile's instructions to discover and apply any repo-local agents or skills it references. For example, the hypershift profile points to .claude/agents/ — read the agents, pick the relevant ones based on changed files, and use their guidance.
Sub-agent: DRY Principle
  • Check for code duplication within and across changed files.
  • Look for repeated patterns that could be extracted into shared functions or utilities.
  • Identify copy-paste code that introduces maintenance risk.
  • Flag magic numbers and string literals that should be constants.
  • If a profile is loaded, check for proper use of project-specific shared utilities (e.g., hypershift's support/ package).
Sub-agent: SOLID Principles
  • Apply SOLID principles proportionally to the scope of the changes:
    • SRP: Does each new function/type/module have one clear responsibility?
    • OCP: Are changes extending behavior without modifying stable abstractions?
    • LSP: Do new implementations honor the contracts of their interfaces?
    • ISP: Are interfaces focused and minimal?
    • DIP: Do high-level modules depend on abstractions rather than concrete implementations?
  • If a profile is loaded, apply any project-specific structural patterns it defines.
Sub-agents: Profile-Specific Reviews (only if profile is loaded)
  • Read the profile skill to discover which SME agents are required.
  • Launch one sub-agent per SME agent listed in the profile. For example, if the profile lists control-plane-sme, data-plane-sme, api-sme, cloud-provider-sme, and hcp-architect-sme, launch five separate sub-agents in parallel, each using the corresponding subagent_type.
  • Each sub-agent must receive:
    • The complete diff
    • PR title and description (if available)
    • The Jira ticket context (if available)
    • A prompt asking it to review the changes from its domain perspective.
  • All profile sub-agents run in parallel with each other and with the other Step 2 sub-agents.

Step 3 — Build Verification

This step can run in parallel with the review sub-agents in Step 2 since it is independent. Skip if --skip-build is specified.

Important: Before running a build, ensure the local checkout matches the PR state. Use gh pr checkout <pr-identifier> to check out the PR branch locally if needed. Ask the user for confirmation before switching branches.

Run build verification in the following priority order:

  1. If a profile skill is loaded, use the profile's build commands first. If the profile doesn't define build commands, fall back to step 2.
  2. Else if a language skill is loaded, use the language skill's build commands.
  3. Otherwise, auto-detect from project files. Check in the following priority order and use the first match found:
    1. Makefile -> make build or make
    2. go.mod -> go build ./...
    3. Cargo.toml -> cargo build
    4. package.json -> npm run build or yarn build
    5. pyproject.toml or setup.py -> python -m py_compile on changed files
  • Run the build command and capture output.
  • If the build fails, report the failure with full output and mark the review as failing.
  • If the build succeeds, note this in the report.

Step 4 — Collect Results & Generate Report

After all sub-agents and build verification complete, aggregate findings into a structured report:

  1. PR Info: PR title, author, base branch, and link.
  2. Files Reviewed: List all files reviewed, categorized by type.
  3. Unit Test Coverage: Findings from the Unit Test Coverage sub-agent. Note if skipped.
  4. Idiomatic [Language] Code: Findings from the Idiomatic Code sub-agent (use detected/specified language name, or "Code" if no language).
  5. DRY Compliance: Findings from the DRY Principle sub-agent.
  6. SOLID Compliance: Findings from the SOLID Principles sub-agent.
  7. Build Verification: Build result (pass/fail/skipped).
  8. Profile-Specific Checks: Findings from the Profile-Specific Review sub-agent (only if profile loaded).
  9. Overall Verdict: PASS, FAIL, or PASS WITH RECOMMENDATIONS.
  10. Required Actions: Issues that must be fixed before merging (blocking).
  11. Recommended Improvements: Suggestions that are not blocking but would improve code quality.

Critical Rules

  • Never approve without build verification unless --skip-build is explicitly specified.
  • Every new exported/public function with non-trivial logic must have tests unless --skip-tests is specified.
  • Be specific: Always reference findings with file:line when possible.
  • Be actionable: Every finding should include a clear recommendation for how to fix it.
  • Be proportional: Review scope should match the scope of changes. A one-line fix does not need a full architectural review.
  • Respect existing patterns: When the codebase has established conventions, follow them rather than imposing new ones.
  • Fix proactively when possible: For simple issues (formatting, missing error checks), offer to fix them directly rather than just reporting.
  • Do not review unchanged code: Focus exclusively on the PR diff. Do not flag pre-existing issues in unchanged code.

Return Value

  • Format: Structured text report with sections as described in Step 4.
  • Success: Report generated with all applicable sections. Verdict is PASS or PASS WITH RECOMMENDATIONS.
  • Failure: Report generated with failing sections identified. Verdict is FAIL with Required Actions listing blocking issues.

Examples

  1. Review a PR by number (in current repo):

    /code-review:pr 456
    

    Fetches PR #456 from the current repo, auto-detects language, and runs a full review.

  2. Review a PR by URL:

    /code-review:pr https://github.com/openshift/hypershift/pull/789
    

    Fetches the PR from the specified repo and runs a full review.

  3. Review with Go language and HyperShift profile:

    /code-review:pr 456 --language go --profile hypershift
    

    Applies Go idiomatic checks plus HyperShift project conventions to PR #456.

  4. Skip build for a docs-only PR:

    /code-review:pr 456 --skip-build
    

    Runs all review steps except build verification.

  5. Python review without tests:

    /code-review:pr 456 --language python --skip-tests
    

    Applies Python idiomatic checks but skips unit test coverage review.

  6. Full review with explicit language, no profile:

    /code-review:pr 456 --language rust
    

    Applies Rust idiomatic checks with no project-specific profile.

Arguments:

  • $1 (required): PR identifier — either a full GitHub PR URL (e.g., https://github.com/owner/repo/pull/123) or a PR number (e.g., 123). When a number is provided, the current repository's remote is used.
  • --language <lang>: Language skill to load. Currently shipped: go. Planned: python, rust, typescript, java. If omitted, auto-detected from changed file extensions.
  • --profile <name>: Project profile skill to load. Loads skills/profile-<name>/SKILL.md for project-specific conventions. If omitted, no profile-specific checks are applied.
  • --skip-build: Skip the build verification step (Step 3). Useful for documentation-only changes or when build infrastructure is not available locally.
  • --skip-tests: Skip the unit test coverage review step (Unit Test Coverage sub-agent). Useful when changes do not affect testable code.

Sponsors

Details

Marketplace
openshift-eng/ai-helpers
Source
plugins/code-review
Category
Development
Keywords
code-review, quality, pre-commit, linting

More from openshift-eng/ai-helpers

All 56