team-review

name	team-review
description	Conduct a code review using the team's reviewer personas. Use this skill when asked to review a PR, review code changes, or get team feedback on code. Loads real reviewer personas from the personas/ directory and reviews as each team member would.

Team Code Review

You conduct code reviews by adopting the personas of real team members, built from their actual PR review history.

Step 0: Locate timrev & Verify Personas

Find the timrev project directory. Check in order:

1. The current working directory (look for personas/ directory and collect.py here)
2. Parent directories up to 3 levels
3. Ask the user where they cloned timrev

Store the resolved path as TIMREV_DIR. Persona files are in $TIMREV_DIR/personas/.

Check that personas exist: List .md files in $TIMREV_DIR/personas/. If the directory is empty or doesn't exist, stop and tell the user:

No team personas found. Please build them first by saying:
"Build reviewer personas for my team"

Do NOT proceed with the review until at least one persona file exists.

Workflow

Step 1: Get the PR

The user should provide a GitHub PR URL, e.g.:

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

Parse the URL to extract: owner, repo name, and PR number.

If no PR URL is provided, ask the user for one.

Step 2: Fetch PR Details

Use the GitHub API to get PR details (authenticated via gh CLI):

gh api /repos/{owner}/{repo}/pulls/{number}

Or via curl:

TOKEN=$(gh auth token)
curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/{owner}/{repo}/pulls/{number}"

Extract:

• title — PR title
• head.ref — source branch (e.g., feature/my-change)
• base.ref — target branch (e.g., main)
• body — PR description

Step 3: Get the Diff

1. Check if the repo is already cloned in $TIMREV_DIR/repos/{repo_name}:

   • If yes: cd $TIMREV_DIR/repos/{repo_name} && git fetch --all -q
   • If no: Clone it:

     gh repo clone {owner}/{repo} $TIMREV_DIR/repos/{repo_name} -- --quiet
     

2. Checkout the source branch and get the diff against the target:

   cd $TIMREV_DIR/repos/{repo_name}
   git checkout {source_branch} -q
   git pull origin {source_branch} -q
   git diff origin/{target_branch}...HEAD
   

3. Store the diff output — this is what the reviewers will analyze.

Step 4: Select Reviewers

List available personas from $TIMREV_DIR/personas/:

Available reviewers:
  1. Alice Smith (personas/alice_smith.md)
  2. Bob Jones (personas/bob_jones.md)
  3. Carol Chen (personas/carol_chen.md)

Who should review? (Enter numbers, names, or "all")

Ask the user to pick reviewers. Accept:

• Numbers from the list (e.g., "1, 3")
• Names (partial match OK, e.g., "Alice")
• "all" for the entire team

Step 4.5: Review Preferences

Before starting the review, ask the user two things using the ask_user tool:

1. Review depth — ask:

   How deep should the review be?
   

   With choices:

   • Quick scan — blocking issues and major red flags only. Short, punchy comments. ~3-5 comments per reviewer.
   • Standard — blocking issues + suggestions + brief positive feedback. Balanced detail. ~5-10 comments per reviewer.
   • Deep dive — thorough analysis of every concern: architecture, naming, edge cases, tests, observability. Detailed explanations with code examples. ~10-20 comments per reviewer.

2. Special focus — ask (freeform):

   Anything specific to focus on? (e.g., "security", "backward compatibility", "performance under load", or just press Enter to skip)
   

Store the chosen depth as review_depth and the special focus as special_focus (empty string if skipped). These are passed to each sub-agent in Step 5.

Step 5: Conduct the Review (Independent Sub-Agents)

CRITICAL: Each reviewer MUST be run in a completely independent sub-agent so that one reviewer's opinions cannot influence another's. Use the task tool with agent_type: "general-purpose" for each reviewer.

For each selected reviewer, launch a separate sub-agent with the following prompt (fill in the variables):

You are {reviewer_full_name}, conducting a code review. You must review ONLY based on your persona below — do not invent opinions outside your documented expertise.

## Your Persona
{paste the FULL contents of their persona .md file here}

## PR Details
- **Title**: {pr_title}
- **Description**: {pr_description}
- **Source**: {source_branch} → **Target**: {target_branch}

## Diff to Review
{paste the full diff here}

## Review Depth: {review_depth}
- If "Quick scan": Only flag blocking issues and major red flags. Keep each comment to 1-2 sentences. No positive feedback section. Aim for ~3-5 comments total.
- If "Standard": Flag blocking issues and suggestions. Include brief positive feedback. Moderate detail. Aim for ~5-10 comments total.
- If "Deep dive": Thorough analysis — architecture, naming, edge cases, error handling, tests, observability. Provide detailed explanations with code examples where helpful. Aim for ~10-20 comments total.

## Special Focus
{special_focus or "None — review based on your natural priorities."}
If a special focus is specified, pay extra attention to that area across the diff, but don't ignore other issues you'd normally catch.

## Instructions
1. Review this diff AS {reviewer_full_name}, using the priorities, principles, communication style, and domain expertise described in your persona.
2. Follow the "How to Review" section from your persona to structure your analysis.
3. Match your communication patterns exactly — how you phrase suggestions vs requirements, whether you use questions or directives, your level of detail.
4. Reference your documented principles when flagging issues (e.g., "Per my Principle 1a: ...").
5. Only comment on areas you have demonstrated knowledge in. Do NOT fabricate expertise.
6. Respect the requested review depth — adjust your verbosity and coverage accordingly.

## Output Format
Write your review in this exact format (no preamble, start directly):

## 🔍 Review by {reviewer_full_name}

<Your review content in your voice and style>

### Blocking Issues
- ...

### Suggestions
- ...

### Positive Feedback
- ...

Parallelism: If there are multiple reviewers, launch all sub-agents in parallel (use mode: "background" for all but the last, then collect results with read_agent). This ensures true independence AND faster execution.

After all sub-agents complete, collect their outputs for Step 6.

Step 6: Save the Review

Write the complete review to a markdown file at:

$TIMREV_DIR/reviews/{repo_name}-{pr_number}.md

Create the $TIMREV_DIR/reviews/ directory if it doesn't exist.

Assemble the file by:

1. Writing the header (you write this part):

   # Team Review: {PR Title} (PR #{pr_number})
   
   > **Repository**: {owner}/{repo}
   > **Source**: {source_branch} → **Target**: {target_branch}
   > **Reviewed by**: {comma-separated reviewer names}
   > **Date**: {current date}
   
   ---
   

2. Appending each sub-agent's review output verbatim (each one already has the ## 🔍 Review by ... heading), separated by ---.

3. Writing the Consolidated Summary (you write this part by analyzing the independent reviews):

   ---
   
   ## Consolidated Summary
   
   - Total issues found
   - Which issues multiple reviewers flagged independently (high confidence — these are the most important)
   - Which issues only one reviewer caught (their specialty area)
   

After saving, tell the user:

✅ Review saved to: reviews/{repo_name}-{pr_number}.md

Guidelines

• Stay in character: Each review should genuinely feel like it came from that person, based on their documented patterns.
• Don't fabricate expertise: Only comment on areas the persona has demonstrated knowledge in. If a persona specializes in observability but not security, don't make up security opinions for them.
• Quote their principles: When flagging an issue, reference the reviewer's documented principles (e.g., "Per Alice's Principle 1a: every swallowed exception needs a metric").
• Differentiate severity: Use the reviewer's own patterns for distinguishing blocking issues from suggestions.
• Be constructive: Match the reviewer's constructive tone — most reviewers explain why, not just what.