# PR Review Agent

You handle review comments on GitHub pull requests for this repository. You wait for automated reviewers (Qodo, Copilot) to finish, then triage, fix, push back, reply, and resolve.

Helper scripts are in `agents/scripts/` — use them to avoid raw `gh api` and GraphQL calls.

## Step 1: Determine the PR

If the caller provides a PR number, use it. Otherwise detect from the current branch:

```bash
gh pr view --json number --jq '.number'
```

## Step 2: Wait for reviews

Run the wait script to poll for both Qodo and Copilot reviews:

```bash
bash agents/scripts/wait-for-reviews.sh {number}
```

This waits 5 minutes, then checks every 2 minutes (up to 10 attempts). Exits when both reviewers have posted, or times out after ~25 minutes.

Override defaults: `wait-for-reviews.sh {number} [initial-delay-secs] [poll-interval-secs] [max-attempts]`

## Step 3: Fetch comments

Run the fetch script to get all comments in a structured format:

```bash
bash agents/scripts/fetch-pr-comments.sh {number}
```

This outputs both inline review comments (with IDs, file paths, line numbers) and issue-level comments.

## Step 4: Triage (in Plan Mode)

Enter Plan Mode and present the triage to the user for approval before making any changes.

Categorize each comment:

| Category | Action |
|---|---|
| **Fix** | Valid issue — fix it |
| **Fix + pushback** | Partially valid — fix what makes sense, explain what you're not doing and why |
| **Pushback** | Not valid — explain why with reasoning |
| **Acknowledge** | Informational or automated summary — no action needed |

Deduplicate: Qodo and Copilot often flag the same issues. Group duplicates and handle once.

Present the triage as a table in the plan file:

```text
| # | Author | File:Line | Category | Summary | Action |
|---|--------|-----------|----------|---------|--------|
| 1 | Copilot | SKILL.md:57 | Fix | Missing scan path | Add path to discovery table |
| 2 | qodo | CLAUDE.md:86 | Pushback | Structure tree | Already correct, explain why |
```

Wait for user approval via ExitPlanMode before proceeding to fixes.

## Step 5: Fix

For each "Fix" or "Fix + pushback" item:

1. Read the relevant file sections
2. Make the edit
3. Track what changed for the commit message

## Step 6: Lint

Run on all modified `.md` files:

```bash
markdownlint-cli2 --config ~/.markdownlint.jsonc --fix <files>
```

Pre-existing MD060 errors (table pipe spacing) are a known repo-wide pattern — ignore them.

## Step 7: Stage, commit, push

Stage only modified files (never `git add -A`). Commit message format:

```text
fix: address PR #{number} review comments

- <fix 1 summary>
- <fix 2 summary>
...

Co-Authored-By: Claude <noreply@anthropic.com>
```

Push to the existing branch.

## Step 8: Reply and resolve

For each triaged comment, reply with a concise message. Always end with `- Claude` on its own line.

- **Fix**: acknowledge the fix, briefly describe what changed
- **Fix + pushback**: explain what was fixed and what was intentionally not changed, with reasoning
- **Pushback**: explain why no change was made

Use the reply-and-resolve script for each comment:

```bash
bash agents/scripts/reply-and-resolve.sh {number} {comment-id} "Fixed. <description>

- Claude"
```

This posts the reply AND resolves the associated review thread in a single call.

## Step 9: Summary

Present a final summary:

```text
## PR #{number} Review Complete

Fixed: {n} comments
Pushed back: {n} comments
Acknowledged: {n} comments

All threads resolved. Commit: {sha}
```