Pr Reviewer Assign

PR Reviewer Assignment Optimizer

CRITICAL: Never use gh CLI, curl, or any other tool to fetch GitHub data. Always use the included fetch_github.py script. It handles all GitHub API calls internally.

Assigns PRs to reviewers using energy-based optimization that discovers context carry-over — reviewing PR #3 (auth module) makes you faster at reviewing PR #7 (also auth). This cross-PR interaction is invisible to per-PR expertise matching.

When to use

• User provides a GitHub repo and wants PR reviewer assignments
• User describes a set of PRs and team members manually
• User wants to understand review load distribution
• User asks about optimizing code review workflow

How it works

The optimizer compares two strategies:

1. Heuristic (expertise matching): assigns each PR to its best-expertise available reviewer independently
2. EBRM (energy-based): optimizes all assignments jointly, discovering that clustering module-related PRs on the same reviewer reduces total review time through context carry-over

Workflow

Step 1: Gather data

Option A — GitHub repo (preferred):

# Fetch all open PRs and infer reviewer expertise from recent history
python3 SKILL_DIR/scripts/fetch_github.py owner/repo \
  --reviewers alice,bob,carol,dave \
  > /tmp/pr_data.json

# Fetch only specific PRs by number
python3 SKILL_DIR/scripts/fetch_github.py owner/repo \
  --prs 42,87,123 \
  --reviewers alice,bob,carol,dave \
  > /tmp/pr_data.json

# For private repos or higher rate limits, the script automatically
# uses the GITHUB_TOKEN environment variable if set.
# A token can also be passed explicitly:
python3 SKILL_DIR/scripts/fetch_github.py owner/repo \
  --token ghp_xxxx \
  --reviewers alice,bob,carol,dave \
  > /tmp/pr_data.json

Replace SKILL_DIR with the actual path to this skill directory. The --reviewers flag is optional; if omitted, the script infers top contributors from recent closed PRs. For private repos, the user needs a GitHub token with repo scope — the script reads $GITHUB_TOKEN automatically, so no need to pass --token if it's already set in the environment.

The script:

• Fetches open PRs with file lists, sizes, labels, authors
• Analyzes the last 50 closed PRs to build expertise profiles per reviewer
• Infers code modules from file paths (e.g. src/auth/token.ts → module "auth")
• Outputs JSON ready for the optimizer

Option B — Manual input:

If the user describes PRs and reviewers in conversation, build the JSON manually:

{
  "prs": [
    {
      "id": "123",
      "title": "Fix auth token refresh",
      "files": ["src/auth/token.ts", "src/middleware/verify.ts"],
      "size": 180,
      "author": "alice",
      "urgent": false,
      "labels": ["bug"]
    }
  ],
  "reviewers": [
    {
      "name": "bob",
      "expertise": {"auth": 0.8, "api": 0.6, "middleware": 0.5},
      "current_load": 1.5,
      "max_hours": 5.0,
      "speed": 1.0
    }
  ],
  "config": {
    "iterations": 80000,
    "context_discount_max": 0.5,
    "seed": 42
  }
}

Expertise scale: 0.0 = no familiarity, 0.5 = comfortable, 0.9 = expert. When building from conversation, estimate conservatively. If unsure, use 0.3 as default.

Speed: 1.0 = average. 0.8 = fast reviewer, 1.2 = thorough/slower.

current_load: hours the reviewer already has committed today. Ask the user or default to 0.

Step 2: Run the optimizer

cat /tmp/pr_data.json | python3 SKILL_DIR/scripts/optimize.py > /tmp/pr_results.json

This runs the heuristic AND the EBRM optimizer (80K iterations, ~15s) and outputs both assignments with a comparison.

Step 3: Present results

Read /tmp/pr_results.json and present:

1. Comparison summary: total hours, context savings %, energy score for heuristic vs optimized
2. Optimized assignments: for each PR, who should review it and why (expertise, context carry-over, time estimate)
3. Reviewer load: hours per reviewer with capacity bar
4. Context clusters: which modules are clustered on which reviewer, and the time savings from clustering
5. Key insight: the specific reassignment(s) where context carry-over beat expertise matching

Format as a clear table. Highlight PRs where the optimized assignment differs from the heuristic and explain WHY the optimizer chose a different reviewer.

Step 4: Adjustments

After showing results, ask if the user wants to:

• Lock specific assignments (add them as constraints and re-run)
• Adjust reviewer availability (change current_load or max_hours)
• Override expertise scores
• Exclude reviewers for specific PRs (e.g. "Bob shouldn't review billing PRs")

For locked assignments, modify the JSON to set those PRs' assignments and reduce the search space for the optimizer.

Output JSON structure

{
  "heuristic": {
    "energy": 410.44,
    "total_hours": 27.5,
    "context_savings_pct": 8.5,
    "assignments": [...],
    "clusters": {"alice": {"prs": ["1","2"], "modules": ["auth","api"]}}
  },
  "optimized": {
    "energy": 204.41,
    "total_hours": 24.22,
    "context_savings_pct": 18.7,
    "assignments": [...],
    "clusters": {...}
  },
  "improvement": {
    "hours_saved": 3.28,
    "extra_context_savings_pct": 10.1,
    "energy_reduction": 206.03
  }
}

Key concepts to explain to the user

• Context carry-over: reviewing code in the same module builds mental context. The second PR touching auth takes ~25-50% less time than the first.
• Why expertise isn't everything: a reviewer with 0.6 expertise who already has context on the module can be faster than a 0.9 expert seeing it cold.
• Energy: a single number combining review hours, overload risk, urgency, and load balance. Lower = better.
• Module detection: inferred from file paths. src/auth/token.ts → "auth". Users can override with explicit modules field in PR data.

Troubleshooting

• GitHub rate limit: use --token flag with a personal access token
• Private repo: token with repo scope required
• Few PRs: optimizer has less room to improve; with <4 PRs the heuristic may be near-optimal
• All same module: if all PRs touch the same code, context carry-over applies everywhere and the optimizer focuses on load balancing instead
• Optimizer finds same as heuristic: this means the heuristic was already good for this particular PR set — the cross-dependencies were weak

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: m1halo
• Source: m1halo/claude-pr-reviewer-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.