Review Prs

Review PRs for Best Practices

Scan recent open PRs in the configured PR repository for violations of

documented best practices.

• Interactive mode (default): drafts comments and asks for user approval

before posting.

• Auto mode (auto argument): posts all violations automatically without

approval. Designed for cron/headless use.

IMPORTANT: This skill only reviews PRs against existing best practices. It

must NEVER create, modify, or add new best practice rules or documentation

during a review run.

Architecture: File-Based Pipeline

The review pipeline minimizes LLM token usage by pushing all heavy data through

files, not context:

• prepare-review.py (zero LLM tokens) — fetches PRs, diffs, comments;

writes subagent prompt files to a temp work directory; outputs a tiny JSON

pointer to the work dir

• Subagents (subagent tokens only) — each reads its prompt from a file,

reviews the diff, validates violations by reading source code, writes results

to a JSON file

• collect-results.py (zero LLM tokens) — reads all result files, feeds to

post-review.py which handles prioritization, dedup, posting, approval, and

notifications

The main LLM session only orchestrates: run scripts, read a small manifest,

launch subagents with tiny prompts, run the collector. It never sees diffs, rule

text, or violation details.

The Job

When invoked with

/review-prs [days|page<N>|#<PR>] [open|closed|all] [auto] [reviewer-priority]:

Step 1: Prepare (zero LLM tokens)

Run the prepare script with all arguments:

SKILL_DIR="<absolute path to .claude/skills/review-prs>"
python3 $SKILL_DIR/prepare-review.py [days|page<N>|#<PR>] [open|closed|all] [--auto] [--reviewer-priority]

The script's stdout is a tiny JSON with work_dir and manifest paths.

Progress and cost summary go to stderr.

Parse the stdout JSON to get work_dir.

Step 2: Read manifest

Read the manifest file at {work_dir}/manifest.json. It contains:

• auto_mode: whether to post without approval
• bot_username: the bot's GitHub username
• pr_repo: the target PR repository
• fetch_summary: stats on how many PRs were fetched/filtered/skipped
• progress_lines: pre-formatted progress messages — print these to stdout

for cron logs

• prs: array of PRs to review, each containing:
• number, title, headRefOid, author, hasApproval
• subagent_prompts: array of entries with prompt_file and results_file

paths (NOT prompt text)

• cached_prs: already-reviewed PRs (handled by prepare script — just log

results)

• errors: per-PR errors encountered during preparation

Print the progress_lines. Log any errors.

For each cached PR, log:

• If approved is true:

APPROVE: PR #N (title) - all threads resolved, approved

• If thread_resolution.unresolved_bot_threads > 0:

CACHED: PR #N (title) - N threads still unresolved

If no PRs to review (empty prs array), skip to Step 4.

Step 3: Launch subagents

For every PR in prs, for every entry in that PR's subagent_prompts, launch a

Task subagent (subagent_type: "general-purpose") with this prompt:

Read your full review instructions from: {prompt_file}
Execute them completely. The instructions contain the PR diff, best practice rules, review rules, and validation requirements.
After reviewing and validating, write your results JSON to the file path specified in the instructions.

Launch ALL subagents across ALL PRs in a single message so they run

concurrently.

CRITICAL: Launch ALL subagents — no exceptions. The prepare script already

filtered documents by file type. Every entry in subagent_prompts MUST get a

subagent. Do NOT skip any.

Wait for all subagents to return.

CRITICAL: NEVER post reviews, comments, or approvals to GitHub yourself. Do

NOT use gh api, gh pr review, gh pr comment, or any GitHub API calls to

post anything on any PR. All posting is handled exclusively by

collect-results.py → post-review.py in Step 4. If you post reviews directly,

it creates duplicates.

Step 4: Collect and post (zero LLM tokens)

Run the collector script — it reads all subagent result files and runs

post-review.py:

python3 $SKILL_DIR/collect-results.py --work-dir "$WORK_DIR" [--auto]

Pass --auto if auto_mode is true.

The script handles everything: collecting violations from result files,

prioritization/capping (5 per PR), rule link validation, deduplication, posting

inline reviews, approval for clean PRs, cache updates, and the final summary

block.

For interactive mode (no --auto): instead of running collect-results.py

directly, read the result files yourself from

{work_dir}/pr_{number}/{chunk_id}_results.json, present each violation to the

user for approval, then write only approved violations back and run

collect-results.py.

Read the script's stderr — it contains the summary. Print it for cron logs.

Summary of what consumes LLM tokens

| Phase | Token cost | Who does it |

| ------------------------------- | --------------------------- | --------------------------------------- |

| Fetch PRs, diffs, comments | Zero | prepare-review.py |

| Build subagent prompts (files) | Zero | prepare-review.py |

| Resolve threads, check approval | Zero | prepare-review.py |

| Read manifest, launch subagents | ~50 tokens per subagent | Main LLM session |

| Rule-checking + validation | Subagent tokens | Subagents (read prompt from file) |

| Collect results, post, approve | Zero | collect-results.py + post-review.py |

PR Link Format

When displaying PR numbers, ALWAYS use a full markdown link:

PR #<number>. NEVER use bare

#<number> — the TUI auto-links them against the wrong repository.

Closed/Merged PR Workflow

When reviewing closed or merged PRs and a violation is found:

• Present the finding to the user (draft comment + ask for approval)
• If approved, try to post inline review comments. If the API fails, fall

back to:

   gh pr comment --repo $PR_REPO {number} --body "[file:line] comment text"

• Create a follow-up issue in $PR_REPO to track the fix:

   gh issue create --repo $PR_REPO --title "Fix: <brief description>" --body "Found during post-merge review of PR #<NUMBER>. <description>"

• Reference the new issue back in the PR comment.