
code-review
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-helpersRun it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.
Contents
Discovered from sourceSkills 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 theallowed_botssection of config.json - Comments matching any pattern in the
noise_patternssection 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_botsin config.json (classify their substantive review comments — code issues, suggestions, questions)
Classification Approach
For each comment:
- Read config.json to load the valid severity and topic values
- Scan the comment body for signal words and patterns that match label descriptions
- Select exactly one severity — match the comment's urgency/tone to the severity descriptions and signals
- Select exactly one topic — match the comment's subject matter to the topic descriptions and examples
- Score confidence using the rubric below
- When ambiguous, prefer the more specific label over
unclassified - 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:
| Signal | Weight | Criteria |
|---|---|---|
| Signal word match | +0.25 | Comment contains signal words/phrases from config.json for the chosen severity or topic label |
| Unambiguous category | +0.25 | Comment clearly fits one severity and one topic with no viable alternatives |
| Example pattern match | +0.25 | Comment closely matches a real-world example in this skill or in config.json |
| Context reinforcement | +0.15 | Multiple independent indicators point to the same classification (e.g., tone + keywords + structure all agree) |
| Single viable label | +0.10 | No 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]
| Argument | Description |
|---|---|
--serial | Run all specialists inline instead of as parallel sub-agents |
--comment | Post the verdict as a PR comment after review. Requires a PR identifier |
--coderabbit | Include CodeRabbit as an external reviewer |
--codex | Include OpenAI Codex as an external reviewer |
-reviewer | Exclude a specialist (e.g., -writer,-qa). All enabled by default |
| pr identifier | GitHub/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 -:
| Specialist | Lens | Reproducer? |
|---|---|---|
| bugs | Functional bugs: missing calls, wrong logic, unhandled edge cases | Yes — mandatory |
| adversarial | Break the code: bad inputs, race conditions, boundary values | Yes — mandatory |
| security | Vulnerabilities, credential handling, dependency trust, supply chain integrity | When claiming a concrete exploit |
| architecture | Structural patterns, SOLID, cross-file impact, module boundaries | No |
| consistency | Duplicate helpers, convention drift, style match with existing code | No |
| qa | Test coverage gaps, missing edge-case tests, concrete test suggestions | No |
| writer | Documentation accuracy, staleness, consistency with code changes | No |
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:
- GitHub URL (
github.com/.../pull/N): setPLATFORM=github,OWNER,REPO,PR_NUMBER=N - GitLab URL (
gitlab.com/.../-/merge_requests/N): setPLATFORM=gitlab,PROJECT(group/subgroup/repo path),MR_IID=N. PreferOWNER/REPOonly when the project path has exactly two segments - Bare integer: detect platform from
git remote -v(GitHub →gh, GitLab →glab), then setPR_NUMBERorMR_IID. DeriveOWNER/REPOorPROJECTfrom 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:
- If a PR/MR is known, use its base ref
(
gh pr view --json baseRefNameorglab mr view --output json) - Discover remotes with
git remote -v(do not hardcodeorigin/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 - 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 probingmainthenmaster(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/:
| Specialist | Prompt |
|---|---|
| bugs | references/specialists/bugs.md |
| adversarial | references/specialists/adversarial.md |
| security | references/specialists/security.md |
| architecture | references/specialists/architecture.md |
| consistency | references/specialists/consistency.md |
| qa | references/specialists/qa.md |
| writer | references/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}.mdfor 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).
- Deduplicate — merge duplicates, keep strongest reproducer
- Filter noise — remove false positives, style nitpicks, speculative findings, and issues already addressed in the branch
- Resolve conflicts — corroboration strengthens; adversarial concerns are blocking unless concretely refuted
- 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
- Prioritize — reproduced security bugs > reproduced functional bugs > unreproduced > architecture > style/docs
- 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/glabnot 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 withgit remote -vwhen 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
-raceflag — avoid shared mutable state between parallel tests - File co-location: Test files must be co-located with source files using the
_test.gosuffix - 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.Servernothttp.HTTPServer). Acronyms are all caps (URL,HTTP,ID) - Error handling: Check every error. Wrap with
fmt.Errorf("context: %w", err)to preserve the chain forerrors.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.Contextas 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:
- Tests:
make testif a Makefile with atesttarget exists; otherwisego test -race ./... - Verification:
make verifyif available; otherwisego vet ./... - Build:
make buildif available; otherwisego 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:
- 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. - 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. - 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 detectionmake verify— full verification suite (code generation, formatting, vetting, linting, tests)make api— required if any files inapi/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:
| Option | Behavior |
|---|---|
--language <lang> | Apply language-specific review guidance. If omitted, detect from changed-file extensions. |
--profile <name> | Apply project-specific conventions and checks. |
--skip-build | Skip build verification and report it as skipped. |
--skip-tests | Skip 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:
- Test coverage — unless
--skip-testswas 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. - Idiomatic code — apply language guidance when available; otherwise assess error handling, naming, clarity, and complexity. Follow relevant project guidance.
- DRY — find duplication, repeated patterns, copy-paste code, and values that should be named constants. Apply profile guidance about shared project utilities.
- Design — assess responsibilities, extensibility, interface contracts, interface size, and dependency direction in proportion to the change.
- 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:
- Profile guidance.
- Language guidance.
- Project detection:
make build(or the documented defaultmake) when aMakefileis present;go build ./...for Go;cargo buildfor Rust;npm run buildoryarn buildfor JavaScript/TypeScript;python -m py_compileon 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:
- Files reviewed, categorized by type.
- Unit-test coverage findings, or that the pass was skipped.
- Idiomatic code findings, naming the language when applicable.
- DRY and design findings.
- Build command and result.
- Profile-specific findings, if applicable.
- Overall verdict:
PASS,FAIL, orPASS WITH RECOMMENDATIONS. - 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:
-
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. -
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
$ARGUMENTSfor 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
- PR identifier (required, first positional argument): Either a full GitHub PR URL (e.g.,
- If no PR identifier is provided, ask the user for one.
- If
--languageis 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.mdrelative 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
--profileis specified, check for the profile skill file atskills/profile-<name>/SKILL.mdrelative 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:
- 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.
- Else if a language skill is loaded, use the language skill's build commands.
- Otherwise, auto-detect from project files. Check in the following priority order and use the first match found:
Makefile->make buildormakego.mod->go build ./...Cargo.toml->cargo buildpackage.json->npm run buildoryarn buildpyproject.tomlorsetup.py->python -m py_compileon 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:
- PR Info: PR title, author, base branch, and link.
- Files Reviewed: List all files reviewed, categorized by type.
- Unit Test Coverage: Findings from the Unit Test Coverage sub-agent. Note if skipped.
- Idiomatic [Language] Code: Findings from the Idiomatic Code sub-agent (use detected/specified language name, or "Code" if no language).
- DRY Compliance: Findings from the DRY Principle sub-agent.
- SOLID Compliance: Findings from the SOLID Principles sub-agent.
- Build Verification: Build result (pass/fail/skipped).
- Profile-Specific Checks: Findings from the Profile-Specific Review sub-agent (only if profile loaded).
- Overall Verdict: PASS, FAIL, or PASS WITH RECOMMENDATIONS.
- Required Actions: Issues that must be fixed before merging (blocking).
- Recommended Improvements: Suggestions that are not blocking but would improve code quality.
Critical Rules
- Never approve without build verification unless
--skip-buildis explicitly specified. - Every new exported/public function with non-trivial logic must have tests unless
--skip-testsis specified. - Be specific: Always reference findings with
file:linewhen 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
-
Review a PR by number (in current repo):
/code-review:pr 456Fetches PR #456 from the current repo, auto-detects language, and runs a full review.
-
Review a PR by URL:
/code-review:pr https://github.com/openshift/hypershift/pull/789Fetches the PR from the specified repo and runs a full review.
-
Review with Go language and HyperShift profile:
/code-review:pr 456 --language go --profile hypershiftApplies Go idiomatic checks plus HyperShift project conventions to PR #456.
-
Skip build for a docs-only PR:
/code-review:pr 456 --skip-buildRuns all review steps except build verification.
-
Python review without tests:
/code-review:pr 456 --language python --skip-testsApplies Python idiomatic checks but skips unit test coverage review.
-
Full review with explicit language, no profile:
/code-review:pr 456 --language rustApplies 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. Loadsskills/profile-<name>/SKILL.mdfor 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- compliancev0.4.1
- consolev0.1.0
- container-imagev0.0.2
- docv0.0.2
- etcdv0.0.2
- gitv0.0.7
- githubv0.3.0
- golangv0.7.0
- gopls-lspv1.0.0
- gwapiv0.0.1
- hcpv0.0.3
- hello-worldv1.0.3
- jirav0.9.8
- lvmsv0.1.1
- marketplace-opsv0.1.2
- metricsv0.3.0
- must-gatherv0.0.3
- native-notificationsv0.0.2
- nid-teamv0.2.2
- nodev0.0.3
- node-bugv0.0.3
- node-cvev0.0.8
- node-onboardingv0.0.3
- node-rpmv0.0.3