centaur-review

What this skill does

Human-AI collaborative code review. You lead the review by narrating your thoughts as you read the code. Claude tracks your comments, runs background analysis, and when you're done, challenges your suggestions and helps craft a polished GitHub review.

> **jj workspace note:** You may be in a non-default jj workspace with no `.git` directory. If `gh` commands fail, set `GIT_DIR` to point to the default workspace: `GIT_DIR=/path/to/default/.git gh pr view ...`

---

## Phase 1: Setup

**1. Parse PR argument** (required):
- The user must provide a PR URL or number as an argument
- If missing, ask: "Which PR should we review? Please provide the URL or number."

**2. Fetch PR context:**
```bash
gh pr view <pr> --json number,title,body,url,headRefName,baseRefName,additions,deletions,changedFiles,files
gh pr diff <pr>
```

**Store the file list and diff in memory** - you'll use this constantly to understand what the user is referring to.

**3. Fetch existing reviews and comments:**
```bash
# Get repo info
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')

# Get all reviews
gh api repos/$REPO/pulls/<number>/reviews

# Get all review comments (line-level)
gh api repos/$REPO/pulls/<number>/comments

# Get conversation comments (top-level)
gh pr view <pr> --comments
```

**Summarize the review history:**

For re-reviews, this is critical context. Analyze and categorize:

- **🔴 Your unaddressed change requests** - Changes you requested that don't appear to be fixed yet
- **❓ Open questions for you** - Questions from author or other reviewers awaiting your response
- **💬 Unresolved threads** - Discussion threads not marked resolved
- **✅ Resolved threads** - What's been addressed since your last review
- **📝 Other reviewers' concerns** - Issues raised by others you should be aware of

**Detect if this is a re-review:**
- Check if you have any previous reviews on this PR
- If yes, note what changed since your last review (commits after your review timestamp)

**4. Extract linked issues from PR body:**
- GitHub issues: Look for patterns like `Fixes #123`, `Closes #456`, `Resolves #789`
- Linear issues: Look for `linear.app` URLs (e.g., `https://linear.app/team/issue/TEAM-123`)

**5. Fetch issue details:**
- For GitHub issues: `gh issue view <number> --json title,body,labels`
- For Linear issues: Use Linear MCP tools if available, otherwise WebFetch the URL

**6. Launch background analysis agents** (all in parallel, non-blocking):

Launch five Task agents with `run_in_background: true`. **Do not present these results until Phase 3.**

1. **Bug Finder** (subagent_type: bug-finder):
   ```
   Find bugs, edge cases, and potential failure modes in this PR:
   - Logic errors and incorrect assumptions
   - Edge cases that aren't handled
   - Error handling gaps
   - Race conditions or concurrency issues
   - Security vulnerabilities

   Focus on significant issues. If nothing notable, say "Nothing to add."

   PR diff: [include diff]
   ```

2. **Code Simplifier** (subagent_type: code-simplifier):
   ```
   Review this PR for unnecessary complexity:
   - Over-engineered solutions
   - Abstractions that aren't needed
   - Code that could be more elegant or direct
   - Opportunities to simplify without losing functionality

   Focus on significant issues, not style preferences. If nothing notable, say "Nothing to add."

   PR diff: [include diff]
   ```

3. **Architecture Reviewer** (subagent_type: code-architect):
   ```
   Review the structural/architectural implications of this PR:
   - Does it change how modules interact?
   - Does it introduce new patterns or deviate from existing ones?
   - Are there changes that affect multiple parts of the codebase?
   - Anything that deserves discussion before merging?

   If nothing notable, say "Nothing to add."

   PR diff: [include diff]
   ```

4. **Requirements Checker** (subagent_type: general-purpose):
   ```
   Compare this PR to the linked issue requirements. Identify:
   - Requirements that are implemented correctly
   - Requirements that are missing or incomplete
   - Things the PR does that weren't in the requirements (scope creep?)
   - Deviations that might need discussion

   If everything looks good, say "Nothing to add."

   PR diff: [include diff]
   Issue: [include issue body]
   ```

5. **CLAUDE.md Compliance** (subagent_type: general-purpose):
   ```
   Check if this PR follows the conventions in the repo's CLAUDE.md file:
   - Coding patterns and styles mentioned
   - Architectural guidelines
   - Testing requirements
   - Any other repo-specific rules

   First, read the CLAUDE.md file in the repo root (if it exists).
   Then check the PR against those guidelines.

   If compliant or no CLAUDE.md exists, say "Nothing to add."

   PR diff: [include diff]
   ```

**7. Display summary and enter review mode:**

Show the user:
- PR title and description
- Files changed (list them with additions/deletions)
- Linked issue summary
- **Review history summary** (if this is a re-review):
  - 🔴 Your unaddressed change requests
  - ❓ Open questions awaiting your response
  - 💬 Unresolved discussion threads
  - 📝 Other reviewers' concerns to be aware of
- "Background analysis running... I'll track your comments as you review. 🚀"

**Then prompt:** "Ready when you are - start narrating your thoughts as you read through the code."

---

## Phase 2: Interactive Review Session

Track the user's observations as they narrate. **Do not show background agent results unless explicitly asked.**

**Maintain a comment tracker** with this structure:
```
Comments:
1. [file:line] [SEVERITY] - comment text
2. [file:start_line-end_line] [SEVERITY] - comment text (for multi-line)
...
```

**Line numbers must be actual file line numbers** (from the new version of the file for additions, old version for deletions). These will be used directly in the GitHub API call.

### Identifying File/Line Locations

**Use the PR context you fetched.** When the user makes an observation:

1. **Check if they mentioned a file or line explicitly** - use it directly
2. **If they quoted code**, search the PR diff for that snippet
3. **If they mentioned a concept** (e.g., "the error handling", "the new endpoint"), check which files in the PR diff contain related code
4. **If still unclear, ask immediately.** Have a LOW bar for asking: "Which file is this about? I see changes in `api.py`, `models.py`, and `tests/test_api.py`"

**Never silently guess wrong.** It's much better to ask than to track a comment on the wrong file.

### Interaction Cadence

- **Brief acknowledgment** after each observation: "Got it - tracking on `api.py:45` as a suggestion 👍"
- **If the user is in flow** (rapid observations), batch: "Tracking all three! 🚀"
- Keep it brief - don't interrupt the user's flow with lengthy responses

### User Commands During Review

- Say a severity word to tag the last comment: "blocking", "important", "suggestion", "question", "nitpick"
- "show comments" or "what do you have" - display current comment list
- "show analysis" - check background agent results (only if explicitly requested)
- "drop last" or "nevermind" - remove the last tracked comment
- "ready" or "done reviewing" - move to Phase 3

### Severity Mapping

- BLOCKING - "blocking", "must fix", "can't merge"
- IMPORTANT - "important", "should fix", "concern"
- SUGGESTION - "suggestion", "idea", "could", "maybe"
- QUESTION - "question", "wondering", "curious", "why"
- NITPICK - "nitpick", "minor", "tiny", "small thing"

---

## Phase 3: Consolidation

When the user says "ready" or "done":

**1. Verify comment locations:**
- For each comment, confirm it's associated with a specific file and line range
- If any are unclear, ask now: "A few comments need locations - which file/lines for [comment]?"

**2. Launch Red Teamer:**

Use the **red-teamer** agent (subagent_type: red-teamer) to challenge the user's comments:

```
The user has reviewed this PR and made the following obse