Code Reviewer

Orchestrate a comprehensive code review by running multiple review strategies in parallel, merging and deduplicating findings into a review file. Supports both remote PRs and local branch changes.

Input

• PR number or URL (optional): Accepts 123, #123, or full URL. If omitted, reviews local changes.
• Base branch (required for local mode): The branch to diff against (e.g., main, develop). If the user does not provide a base branch when reviewing local changes, prompt them for it before proceeding.

Procedure

1. Determine Review Target

• Remote PR: If the user provides a PR number or URL (e.g., "Review PR #123"), target that remote PR. Set MODE=pr.
• Local Changes: If no specific PR is mentioned, or if the user asks to "review my changes", target the current local file system changes (staged and unstaged). Set MODE=local.

2. Resolve Identifier and Repository

REVIEWS_DIR=~/.agents/arinhub/code-reviews

If MODE=pr:

MODE=pr
PR_NUMBER=<extracted from user input>
REPO_NAME=$(basename -s .git "$(git remote get-url origin)")
REVIEW_ID=${MODE}-${REPO_NAME}-${PR_NUMBER}
REVIEW_FILE=${REVIEWS_DIR}/code-review-${REVIEW_ID}.md

# Get the PR branch name, base branch, URL, and title from PR metadata (single API call).
PR_META=$(gh pr view ${PR_NUMBER} --json headRefName,baseRefName,url,title)
PR_BRANCH=$(echo "$PR_META" | jq -r '.headRefName')
PR_BASE=$(echo "$PR_META" | jq -r '.baseRefName')
PR_URL=$(echo "$PR_META" | jq -r '.url')
PR_TITLE=$(echo "$PR_META" | jq -r '.title')

If MODE=local:

Before proceeding: If the user did not provide a base branch, prompt them with: "Which base branch should I diff against? (e.g., main, develop)" and wait for their response. Do not auto-detect or fall back to a default.

MODE=local
REPO_NAME=$(basename -s .git "$(git remote get-url origin)")
BRANCH_NAME=$(git branch --show-current | tr '/' '-')
REVIEW_ID=${MODE}-${REPO_NAME}-branch-${BRANCH_NAME}
REVIEW_FILE=${REVIEWS_DIR}/code-review-${REVIEW_ID}.md

# BASE_BRANCH is provided by the user (required).
BASE_BRANCH=<user-provided base branch>

# Find the point where the current branch diverged from the base branch.
MERGE_BASE=$(git merge-base "${BASE_BRANCH}" HEAD)

Create ~/.agents/arinhub/code-reviews/ and ~/.agents/arinhub/diffs/ directories if they do not exist.

Collision avoidance: Check whether a review file or any subagent files for this REVIEW_ID already exist. If so, append a sequential number suffix to produce a unique REVIEW_ID.

BASE_REVIEW_ID=${REVIEW_ID}

if compgen -G "${REVIEWS_DIR}/code-review-${BASE_REVIEW_ID}.md" > /dev/null 2>&1 || \
   compgen -G "${REVIEWS_DIR}/subagent-*-${BASE_REVIEW_ID}.md" > /dev/null 2>&1; then
  N=1
  while compgen -G "${REVIEWS_DIR}/code-review-${BASE_REVIEW_ID}-${N}.md" > /dev/null 2>&1 || \
        compgen -G "${REVIEWS_DIR}/subagent-*-${BASE_REVIEW_ID}-${N}.md" > /dev/null 2>&1; do
    N=$((N + 1))
  done
  REVIEW_ID=${BASE_REVIEW_ID}-${N}
  REVIEW_FILE=${REVIEWS_DIR}/code-review-${REVIEW_ID}.md
fi

3. Initialize Review File

If MODE=pr:

Create the review file with a header:

# PR Review: ${REPO_NAME} #${PR_NUMBER}

**Date:** <current date>
**Repo:** ${REPO_NAME}
**Branch:** ${PR_BRANCH}
**Base Branch:** ${PR_BASE}
**PR Number:** ${PR_NUMBER}
**PR Title:** ${PR_TITLE}
**PR Link:** ${PR_URL}

## Issues

<!-- Issues from parallel review agents merged below. No duplicates. -->

If MODE=local:

Create the review file with a header:

# Local Review: ${REPO_NAME} (${BRANCH_NAME})

**Date:** <current date>
**Repo:** ${REPO_NAME}
**Branch:** ${BRANCH_NAME}
**Base Branch:** ${BASE_BRANCH} (merge base: ${MERGE_BASE})

## Issues

<!-- Issues from parallel review agents merged below. No duplicates. -->

4. Prepare Diff and Working Tree

Save the diff to a shared file so subagents can read it. In remote mode, also check out the PR branch so tools that require a working tree (e.g., react-doctor) operate on the correct code.

If MODE=pr:

DIFF_FILE=~/.agents/arinhub/diffs/diff-${REVIEW_ID}.diff

# Save the current branch so we can return to it after the review.
ORIGINAL_BRANCH=$(git branch --show-current)

# Stash any uncommitted local changes to prevent data loss during checkout.
STASH_MSG="ah-review-code: auto-stash ${REVIEW_ID}"
git stash --include-untracked -m "${STASH_MSG}"

gh pr diff ${PR_NUMBER} > ${DIFF_FILE}

# Check out the PR branch to ensure the working tree reflects the PR code
# for subagents that require it (e.g., react-doctor).
# If checkout fails, restore stashed changes and abort the review.
if ! gh pr checkout ${PR_NUMBER}; then
  STASH_INDEX=$(git stash list | grep -m1 "${STASH_MSG}" | sed 's/stash@{\([0-9]*\)}.*/\1/')
  [ -n "$STASH_INDEX" ] && git stash pop stash@{$STASH_INDEX}
  echo "ERROR: Failed to check out PR #${PR_NUMBER}. Review aborted."
  exit 1
fi

If MODE=local:

Diff from the merge base (resolved in Step 2) to the current working tree. This captures all changes on the feature branch — both committed and uncommitted — relative to the source branch. Note: untracked files (new files not yet git add-ed) are not included in the diff. To include new files in the review, stage them first with git add -N <file> (intent-to-add) before running the review.

DIFF_FILE=~/.agents/arinhub/diffs/diff-${REVIEW_ID}.diff

# Diff from the merge base to the current working tree.
# BASE_BRANCH and MERGE_BASE were resolved in Step 2.
git diff "${MERGE_BASE}" > "${DIFF_FILE}"

No checkout is needed in local mode — the working tree already contains the changes.

5. Detect React Code

Spawn a lightweight subagent (use fast model) to analyze ${DIFF_FILE} and determine whether the changes contain React code. The subagent must read the diff file and return HAS_REACT=true or HAS_REACT=false.

Set HAS_REACT=true if any of these conditions are found in the diff:

• File extensions: Changed files include .tsx, .jsx, or paths under common React directories (e.g., components/, hooks/, pages/)
• React core imports: import ... from 'react', import ... from "react", require('react'), require("react")
• React DOM: import ... from 'react-dom', import ... from 'react-dom/client'
• JSX syntax: Diff hunks contain JSX elements (<Component, <div, />, React.createElement)
• React hooks: Usage of useState, useEffect, useRef, useMemo, useCallback, useContext, useReducer, useLayoutEffect, or custom use* hooks
• React ecosystem packages: Imports from react-router, react-hook-form, @tanstack/react-query, @tanstack/react-table, react-redux, zustand, jotai, recoil, next, @next/, styled-components, @emotion/, or similar React-centric libraries

Otherwise set HAS_REACT=false.

6. Launch Parallel Review Subagents

Spawn subagents in parallel (do not wait for one to finish before starting the next). No subagent may submit a review — they only return findings.

Each subagent writes to its own dedicated file:

SUBAGENT_FILE=~/.agents/arinhub/code-reviews/subagent-<agent-name>-${REVIEW_ID}.md

Where <agent-name> is one of: code-reviewer, octocode-roast, pr-review-toolkit, react-doctor.

Before launching the subagents, read the issue format specification from issue-format.md and embed its full content directly into each subagent prompt. This ensures subagents have the format regardless of the current working directory.

Every subagent prompt must include the following shared context:

The working tree is checked out on the branch that contains the changes under review. A diff file at ${DIFF_FILE} contains all the changes to review. Do not switch branches, run gh pr checkout, or modify the working tree. Do not submit any review.

Output: Write your findings to ${SUBAGENT_FILE} (your dedicated output file). Use the issue format specification embedded in your prompt above.

Delegation rule (applies to ALL subagents A–D): Each subagent's sole job is to invoke its assigned skill and return whatever the skill produces. Do NOT perform the analysis yourself. Do NOT write review logic, diagnostic logic, or generate findings manually. Each skill contains its own methodology — delegate to it completely.

• If HAS_REACT=true: spawn four subagents (A, B, C, D).
• If HAS_REACT=false: spawn three subagents (A, B, C) — skip Subagent D.

Subagent A: code-reviewer

• File: ~/.agents/arinhub/code-reviews/subagent-code-reviewer-${REVIEW_ID}.md
• Invoke: /code-reviewer

Subagent B: octocode-roast

• File: ~/.agents/arinhub/code-reviews/subagent-octocode-roast-${REVIEW_ID}.md
• Invoke: /octocode-roast
• Extra Arguments: add code review

Subagent C: pr-review-toolkit

• File: ~/.agents/arinhub/code-reviews/subagent-pr-review-toolkit-${REVIEW_ID}.md
• Invoke: /pr-review-toolkit:review-pr
• Extra Arguments: add all parallel

Subagent D: react-doctor (only if HAS_REACT=true)

• File: ~/.agents/arinhub/code-reviews/subagent-react-doctor-${REVIEW_ID}.md
• Invoke: /react-doctor
• Extra Output: add full diagnostic report in the subagent's response for merging into the final review file

7. Merge and Deduplicate Issues

Read all subagent output files (~/.agents/arinhub/code-reviews/subagent-*-${REVIEW_ID}.md) and deduplicate:

1. Parse each agent section (identified by ### <agent-name> headings) into individual issues.
2. For each issue, create a fingerprint from: file path + line number range + concern type (e.g., security, correctness, performance, maintainability, style — inferred from the issue description).
3. Two issues are duplicates if they share the same file, overlapping line ranges (within ±5 lines), and address the same concern type (use semantic comparison of descriptions, not exact string matching).
4. When duplicates are found, keep the most detailed/actionable version.
5. Tag each kept issue with its source(s): [code-reviewer], [octocode-roast], [pr-review-toolkit], [react-doctor], or combination if multiple agents found it.
6. Transform each issue's **File:** field from the plain path in issue-format into the linked format used in review-format: combine the file path with the **Line(s):** value to produce a markdown link — e.g., **File:** [path/to/file.ts:42](/absolute/path/to/file.ts#L42) for single lines or **File:** [path/to/file.ts:42-50](/absolute/path/to/file.ts#L42-L50) for ranges.

8. Write Issues to Review File

Append deduplicated issues to the review file, grouped by severity. Use the format defined in review-format.md.

9. React Health Report

Skip this step if HAS_REACT=false.

Follow the instructions in react-health-report.md.

10. Verify Requirements Coverage

Spawn a subagent to execute the /ah-verify-requirements-coverage skill. The subagent's sole job is to invoke the skill and return its output.

• Invoke: /ah-verify-requirements-coverage
• CRITICAL: Do NOT perform requirements verification yourself. Do NOT write verification logic or analyze coverage manually. The skill contains its own methodology — delegate to it completely and return whatever it produces (full requirements coverage report in markdown format).

If MODE=pr: Pass PR ${PR_NUMBER} and ${DIFF_FILE} as arguments to the skill. If a linked issue number was identified during the review (e.g., from PR body or metadata), pass it as well to avoid redundant API lookups. The skill will resolve the linked issue on its own if no issue number is provided.

If MODE=local: Pass ${DIFF_FILE} as an argument to the skill. The skill will attempt to extract the linked issue number from the branch name (e.g., feature/42-description, fix/42, issue-42-description). If no issue can be determined, the skill will skip coverage verification and report that no linked issue was found.

Append the returned coverage report to the end of the review file under a new section:

## Requirements Coverage

<coverage report content from ah-verify-requirements-coverage>

11. Submit PR Review

Skip this step if MODE=local.

Wait for Step 10 — do not proceed until the Verify Requirements Coverage subagent has completed and its report has been appended to the review file.

Follow the instructions in submit-pr-review.md. The subagent returns an Issues Table — append it to the end of ${REVIEW_FILE}.

12. Restore Working Tree

Skip this step if MODE=local.

Follow the instructions in restore-working-tree.md.

13. Report to User

If MODE=pr:

Present a summary:

• Path to the review file
• Total issues found (by severity)
• Requirements coverage percentage with one-line summary (if available)
• Whether the review was submitted successfully
• The PR URL for reference
• Present the Issues Table (returned by the ah-submit-code-review subagent in Step 11)

If MODE=local:

Present the review file (${REVIEW_FILE}) content to the user and a summary:

• Path to the review file
• Total issues found (by severity)
• Requirements coverage percentage with one-line summary (if available)
• Branch name and list of changed files reviewed

Important Notes

• Review subagents run in parallel to minimize total review time (three or four, depending on whether the changes contain React code).
• The react-doctor subagent is only launched when the diff contains .tsx/.jsx files or React imports. This avoids unnecessary React diagnostics on non-React changes.
• The review file is the single source of truth — all findings are merged there before submission.
• Deduplication uses semantic comparison: if two agents flag the same concern on the same code, only one entry is kept.
• The review file persists at ~/.agents/arinhub/code-reviews/ for future reference and audit.
• If a subagent fails or times out, proceed with results from the remaining agents and note the failure in the review file.
• The diff file persists at ~/.agents/arinhub/diffs/ and is shared read-only across all subagents. The PR branch checkout happens once in Step 4 before subagents launch — no subagent should run gh pr checkout or switch branches on its own.
• In MODE=local, step 12 (Submit PR Review) is skipped — the review is output only to the review file and presented to the user. Step 11 (Verify Requirements Coverage) runs if a linked issue can be determined from the branch name or user input.