Resolving Pr Issues

Multi-Agent PR Issue Resolver

Resolve review suggestions using parallel verification and confidence scoring.

Core Principle: Never assume a review comment is correct. Verify every suggestion against actual code before acting.

Input Detection

Detect input mode from $ARGUMENTS:

• PR mode: argument is a number (123) or contains github.com/starts with http — use gh API
• File mode: argument contains / or .md or file exists on disk — parse findings from file
• No argument: show usage hint and stop

Phase 1 — Context Gathering

PR mode — launch 2 parallel Haiku agents:

Agent A — PR Metadata: Run gh pr view $ARGUMENTS --json number,title,body,baseRefName,headRefName,state,author,reviewRequests,statusCheckRollup and gh pr diff $ARGUMENTS. Return: PR summary, base/head branches, CI status, files changed.

Agent B — Comment Extraction: Fetch all review comments using both endpoints:

• Inline review comments: gh api repos/{owner}/{repo}/pulls/{pr}/comments
• General issue comments: gh api repos/{owner}/{repo}/issues/{pr}/comments

Return structured list: comment ID, author, type (inline/general), file:line (if inline), body text, resolved status, whether it contains a suggestion code block.

File mode — launch 1 Haiku agent:

Parse the review report file. Extract each finding: description, file:line, category, suggested fix. Detect format from review/skills/code-review/ report template or other common review formats.

Skip conditions: If no unresolved comments/findings exist, report "Nothing to resolve" and stop.

Phase 2 — Parallel Verification

For each unresolved comment/finding, launch a parallel Sonnet agent (batched in groups of 5):

Each agent receives: the comment text, 50 lines of file context around the referenced line, the PR diff (or current branch diff in file mode), and the PR description.

Each agent returns:

Verdict: CONFIRMED | FALSE-POSITIVE | AMBIGUOUS
Category: Blocker | Bug | Code Quality | Style | Question
Confidence: 0-100
Evidence: {what was checked and found}
Suggested resolution: {specific code change or response text}

See WORKFLOW.md for agent prompt template and false positive filtering rules.

Phase 3 — Triage Report

Filter findings scoring below 80. Present a structured report:

## Review Issue Triage — {repo} PR #{number}
{N} comments analyzed, {M} actionable

### CONFIRMED ({count})
| # | Comment | File:Line | Category | Confidence | Action |
|---|---------|-----------|----------|------------|--------|
| 1 | {summary} | src/auth.ts:45 | Bug | 92 | Fix: add null check |

### FALSE POSITIVE ({count})
| # | Comment | File:Line | Confidence | Reason |
|---|---------|-----------|------------|--------|
| 2 | {summary} | src/api.ts:12 | 15 | Handled by framework |

### AMBIGUOUS ({count})
| # | Comment | File:Line | Options |
|---|---------|-----------|---------|
| 3 | {summary} | src/db.ts:78 | Option A: refactor / Option B: keep + comment |

User approval gate: Present the report and wait for the user to approve, modify, or reject the resolution plan before proceeding. For AMBIGUOUS items, let the user choose. For suggestions offering multiple options, present all and let the user decide.

Phase 4 — Apply Changes

Execute the approved plan:

1. PR mode: gh pr checkout $ARGUMENTS; File mode: use current branch 2. For each approved fix (priority order: Blockers > Bugs > Code Quality > Style):

• Edit the code as planned
• Run targeted tests to verify the fix
• Confirm no regressions in related functionality
• Commit immediately: fix(scope): description — addresses review comment on [topic]

3. If tests fail, investigate root cause — do not skip or force-pass

See WORKFLOW.md for commit message format and priority ordering.

Phase 5 — Update PR

PR mode only (skip entirely in file mode):

1. Push commits to the PR head branch 2. Reply to each comment using the correct mechanism:

• Inline review comments: gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies -f body="..."
• General PR comments: post a single consolidated response with anchor links: ### Re: [Finding title](#issuecomment-{id})

3. Resolution status formats:

• Resolved: "Addressed in commit abc1234 — [brief description]"
• False positive: evidence-based explanation (see WORKFLOW.md for template)
• Deferred: "Created follow-up issue #xyz — [reason]"

4. Re-request reviews: gh pr edit $ARGUMENTS --add-reviewer <username>

Confidence Scoring Rubric

Threshold: Filter out findings below 80.

Resources

• WORKFLOW.md — Agent prompt templates, false positive rules, scoring details, reply formats
• EXAMPLES.md — End-to-end orchestration examples for PR and file modes
• TROUBLESHOOTING.md — Common issues with gh CLI, comment API, and multi-agent pipeline

PR Issue Resolver: Examples

Real-world scenarios showing the skill in action.

For quick start instructions, see SKILL.md. For detailed workflow, see WORKFLOW.md.

---

Example 1: Standard PR with Mixed Feedback

Scenario

A PR adding JWT authentication has 5 review comments from two reviewers.

Command

/resolve-review 142

Phase 1 — Context Gathering

Two Haiku agents fetch PR metadata and comments in parallel:

• PR #142: "Add JWT authentication middleware" — 4 files changed, CI passing
• 5 unresolved comments: 2 from @alice (security focus), 3 from @bob (code quality)

Phase 2 — Parallel Verification

5 Sonnet agents verify each comment (all in one batch since <= 5):

Phase 3 — Triage Report

## Review Issue Triage — myorg/myapp PR #142
5 comments analyzed | 3 actionable (threshold: 80) | 1 false positive | 1 question

### CONFIRMED (2)
| # | Author | File:Line | Category | Confidence | Action |
|---|--------|-----------|----------|------------|--------|
| 1 | @alice | src/auth/middleware.ts:45 | Bug | 95 | Fix: add expiry check |
| 3 | @bob | src/auth/middleware.ts:30 | Code Quality | 82 | Refactor: extract helper |

### FALSE POSITIVE (1)
| # | Author | File:Line | Confidence | Reason |
|---|--------|-----------|------------|--------|
| 2 | @alice | src/auth/cors.ts:12 | 12 | CORS is configured in Express middleware upstream |

### FILTERED (1)
| # | Author | File:Line | Confidence | Reason |
|---|--------|-----------|------------|--------|
| 4 | @bob | src/auth/middleware.ts:23 | 55 | Style nit below threshold |

### QUESTIONS (1)
| # | Author | Comment | Suggested Response |
|---|--------|---------|-------------------|
| 5 | @bob | "Why not Passport.js?" | Custom middleware chosen for minimal footprint |

User approves: "Go ahead with all of it."

Phase 4 — Apply Changes

Checking out PR #142...
[1/2] Fix: add token expiry validation (src/auth/middleware.ts:45)
  → Running tests... 12 passed
  → Committed: fix(auth): validate token expiry — addresses review comment on null handling
[2/2] Refactor: extract token validation helper (src/auth/middleware.ts:30)
  → Running tests... 12 passed
  → Committed: refactor(auth): extract validateToken helper — addresses review comment on code structure

Phase 5 — Update PR

Pushed 2 commits to feature/jwt-auth
Replied to @alice comment #1: "Addressed in commit abc1234 — added expiry check"
Replied to @alice comment #2: "Thanks for flagging. CORS origin is configured in the Express
  middleware layer (see src/app.ts:15). The auth middleware runs after CORS is already applied."
Replied to @bob comment #3: "Addressed in commit def5678 — extracted to validateToken()"
Replied to @bob comment #5: "We chose custom middleware for minimal footprint — Passport.js
  adds 15 dependencies and we only need JWT verification."
Re-requested review from @alice, @bob

---

Example 2: False Positive Heavy

Scenario

A reviewer misunderstood the React component architecture and left 4 comments, 3 of which are false positives.

Command

/resolve-review 87

Phase 3 — Triage Report

## Review Issue Triage — myorg/frontend PR #87
4 comments analyzed | 1 actionable | 3 false positives

### CONFIRMED (1)
| # | Author | File:Line | Category | Confidence | Action |
|---|--------|-----------|----------|------------|--------|
| 3 | @charlie | src/hooks/useAuth.ts:22 | Bug | 88 | Fix: add cleanup in useEffect |

### FALSE POSITIVE (3)
| # | Author | File:Line | Confidence | Reason |
|---|--------|-----------|------------|--------|
| 1 | @charlie | src/components/Modal.tsx:15 | 10 | XSS concern — React auto-escapes JSX output |
| 2 | @charlie | src/components/Form.tsx:40 | 18 | "Missing validation" — handled by Zod schema on line 12 |
| 4 | @charlie | src/pages/Dashboard.tsx:8 | 20 | "Component re-renders too often" — already wrapped with React.memo |

Phase 5 — Replies

The false positive replies are professional and evidence-based:

@charlie comment #1:
Thanks for flagging XSS concerns. React auto-escapes all values embedded in JSX,
so `{user.name}` is safe. We'd only need explicit sanitization if we were using
raw HTML injection APIs, which we don't use in this component. See React docs on
built-in XSS protection.

@charlie comment #2:
Good catch to look for validation — it's handled by the Zod schema defined on
line 12 of this file. The `formSchema.parse()` call on line 38 validates all
fields before submission. Let me know if the schema needs additional constraints.

---

Example 3: Conflicting Reviewer Suggestions

Scenario

Two reviewers disagree on error handling strategy for an API endpoint.

Command

/resolve-review 203

Phase 3 — Triage Report

## Review Issue Triage — myorg/api PR #203
3 comments analyzed | 1 actionable | 2 ambiguous

### CONFIRMED (1)
| # | Author | File:Line | Category | Confidence | Action |
|---|--------|-----------|----------|------------|--------|
| 1 | @alice | src/api/users.ts:67 | Bug | 91 | Fix: handle 404 case |

### AMBIGUOUS (2)
| # | Author | File:Line | Options |
|---|--------|-----------|---------|
| 2 | @alice | src/api/users.ts:45 | Use try/catch with typed errors (Alice's preference) |
| 3 | @bob | src/api/users.ts:45 | Use Result<T,E> pattern (Bob's preference) |

Note: Comments #2 and #3 conflict — both address error handling at the same location.

User Decision

User is presented with both options:

Comments #2 and #3 conflict on error handling at src/api/users.ts:45:

Option A (@alice): try/catch with typed error classes
  + Familiar pattern, matches existing codebase
  - Verbose, error types can drift

Option B (@bob): Result<T,E> monad pattern
  + Type-safe, explicit error paths
  - New pattern, team unfamiliar

Which approach do you prefer?

User chooses: "Option A — matches what we already do."

Phase 5 — Reply

@bob comment #3:
Thanks for the Result<T,E> suggestion — it's a solid pattern. After discussion,
we decided to stick with try/catch + typed errors to maintain consistency with
the rest of the API layer. We may revisit this pattern for future modules.

---

Example 4: Out-of-Scope Suggestions

Scenario

A reviewer leaves valid suggestions that are unrelated to the PR's purpose.

Command

/resolve-review 156

Phase 3 — Triage Report

## Review Issue Triage — myorg/api PR #156
4 comments analyzed | 1 actionable | 1 out-of-scope | 2 false positives

### CONFIRMED (1)
| # | Author | File:Line | Category | Confidence | Action |
|---|--------|-----------|----------|------------|--------|
| 1 | @dave | src/api/orders.ts:89 | Bug | 94 | Fix: handle empty cart |

### OUT-OF-SCOPE (1)
| # | Author | File:Line | Suggestion |
|---|--------|-----------|------------|
| 3 | @dave | src/api/orders.ts:12 | "This whole file needs better test coverage" |

Phase 4-5 — Resolution

The out-of-scope suggestion gets a follow-up issue:

gh issue create --title "Improve test coverage for orders API" \
  --body "Identified during PR #156 review by @dave.

The orders API module currently has limited test coverage.
Suggested areas: edge cases for empty cart, payment failures, concurrent orders.

Ref: PR #156 review comment"

Reply:

@dave comment #3:
Valid point — I've created issue #234 to track test coverage improvements
for the orders module. Out of scope for this PR (focused on cart validation)
but definitely worth addressing.

---

Example 5: File Mode — Local Review Report

Scenario

A code review was generated locally using /review:code-review and saved to a file. The developer wants to resolve the findings without PR context.

Command

/resolve-review reviews/code/2026-03-18_14-30-00_code-review.md

Phase 1 — File Parsing

The Haiku agent parses the review file and extracts:

4 findings extracted from reviews/code/2026-03-18_14-30-00_code-review.md:
1. [Blocker] src/auth/middleware.ts:45 — JWT secret used without null check (Source: Security)
2. [Improvement] src/api/routes.ts:23 — Missing rate limit on public endpoint (Source: Bug Scan)
3. [Improvement] src/db/queries.ts:67 — N+1 query in user list endpoint (Source: Bug Scan)
4. [Nit] src/utils/format.ts:12 — Unused import (Source: CLAUDE.md)

Phase 2-3 — Verification and Triage

Same verification flow as PR mode. The triage report omits PR-specific fields:

## Review Issue Triage — Local Review
4 findings analyzed | 3 actionable | 1 filtered

### CONFIRMED (3)
| # | File:Line | Category | Confidence | Action |
|---|-----------|----------|------------|--------|
| 1 | src/auth/middleware.ts:45 | Blocker | 95 | Fix: add env var validation |
| 2 | src/api/routes.ts:23 | Code Quality | 83 | Fix: add rate limiter |
| 3 | src/db/queries.ts:67 | Code Quality | 81 | Fix: use JOIN instead of N+1 |

### FILTERED (1)
| # | File:Line | Confidence | Reason |
|---|-----------|------------|--------|
| 4 | src/utils/format.ts:12 | 55 | Linter territory — below threshold |

Phase 4 — Apply Changes

Fixes are applied to the current branch (no PR checkout):

Using current branch: feat/jwt-auth
[1/3] Fix: add JWT_SECRET validation (src/auth/middleware.ts:45)
  → Committed: fix(auth): validate JWT_SECRET env var — addresses review finding on null handling
[2/3] Fix: add rate limiter to public endpoint (src/api/routes.ts:23)
  → Committed: fix(api): add rate limit to public routes — addresses review finding on missing limits
[3/3] Fix: replace N+1 with JOIN (src/db/queries.ts:67)
  → Committed: fix(db): use JOIN for user list query — addresses review finding on N+1 pattern

Phase 5 — Skipped

No PR to update in file mode. The fixes are committed locally for the user to push when ready.

---

Common Patterns

1. Most PRs have some false positives: Expect 20-40% of comments to be filtered. This is normal — reviewers often flag concerns based on incomplete context. 2. Confidence scoring prevents over-correction: Without scoring, you'd blindly apply every suggestion. The threshold ensures only high-confidence issues get fixed. 3. Questions deserve thoughtful responses: Don't dismiss "Why?" questions — they often reveal misunderstandings that, if left unaddressed, lead to the same feedback on future PRs. 4. File mode is great for self-review: Run /review:code-review first, then /resolve-review on the report to fix findings before opening a PR. 5. One commit per fix: Keeps the git history clean and makes it easy for reviewers to see exactly what was changed for each comment.

PR Issue Resolver: Troubleshooting

Solutions to common issues when using the resolving-pr-issues skill.

For quick start instructions, see SKILL.md. For detailed workflow, see WORKFLOW.md. For examples, see EXAMPLES.md.

---

gh CLI Issues

Issue: Authentication Failure

Symptom: All gh commands fail with "authentication required" or "401 Unauthorized".

Solution:

gh auth status    # Check current auth
gh auth login     # Re-authenticate

Ensure the token has repo scope for private repositories and read:discussion for PR comments.

Issue: Rate Limiting

Symptom: gh api calls fail with "403 rate limit exceeded".

Solution: Wait for the rate limit to reset (shown in the error message). For large PRs with many comments, the skill batches API calls to stay within limits. If the issue persists, use a personal access token with higher rate limits.

Issue: Missing Repository Permissions

Symptom: Can view PR but cannot post comments or push commits.

Solution: Ensure your token has repo scope (not just public_repo). For organization repos, check that your account has write access to the repository.

---

Comment API Issues

Issue: Inline vs General Comment Confusion

Symptom: Reply posted as a new general comment instead of in the review thread.

Cause: GitHub has two separate comment APIs:

• Inline review comments: pulls/{pr}/comments — supports thread replies
• General issue comments: issues/{pr}/comments — does NOT support threading

Solution: The skill detects comment type in Phase 1. Inline comments are replied to via the thread API. General comments get a single consolidated response with anchor links. If misclassified, check the comment ID format — inline comments have pull_request_review_id and diff_hunk fields.

Issue: 404 on Comment Reply

Symptom: gh api returns 404 when replying to a comment.

Causes:

• Comment was deleted by the reviewer after extraction
• Comment ID is from the wrong API endpoint (inline ID used with general endpoint or vice versa)
• PR was closed or merged between Phase 1 and Phase 5

Solution: Re-fetch the comment to verify it still exists. If deleted, skip the reply. If the PR was closed, inform the user and skip Phase 5.

Issue: Reply Creates Duplicate Thread

Symptom: Multiple reply threads appear on the same review comment.

Cause: Retrying a failed reply that actually succeeded (network timeout with server-side success).

Solution: Before retrying a reply, check if your response already appears in the thread via gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies.

---

Multi-Agent Pipeline Issues

Issue: Verification Agent Timeout

Symptom: One or more Phase 2 agents don't return results.

Solution: The skill continues with results from successful agents and notes the gap in the triage report. If most agents fail, it falls back to sequential verification (reading the code directly instead of using agents).

Issue: Zero Actionable Comments Found

Symptom: Phase 1 returns no unresolved comments.

Causes:

• All review threads are already resolved
• PR has only bot comments (CI, coverage) or approval comments
• Comments are from the PR author (self-review, filtered out)

Solution: The skill reports "Nothing to resolve" and stops. If you believe comments exist, check the PR directly with gh pr view {number} and verify review threads are unresolved.

Issue: All Findings Filtered (Below Threshold)

Symptom: Phase 2 returns findings but all score below 80.

Solution: This means the verification agents determined all suggestions are low-confidence (false positives or nitpicks). The skill presents the filtered results for transparency and asks if you want to lower the threshold or address specific items anyway.

---

Resolution Issues

Issue: Merge Conflict After Applying Changes

Symptom: git push fails with merge conflict after committing fixes.

Solution: Rebase the branch against the base:

git fetch origin
git rebase origin/{base-branch}
# Resolve conflicts
git push --force-with-lease

The skill attempts rebase automatically. If conflicts are complex, it stops and asks for help.

Issue: Tests Fail After Fix

Symptom: A fix addresses the review comment but breaks existing tests.

Solution: The skill stops immediately when tests fail — it does not push broken code. Investigate the root cause: the fix may need adjustment, or the test may need updating. The skill presents the failure and asks for guidance before continuing.

Issue: Pre-Commit Hook Blocks Commit

Symptom: Commit fails due to linting, formatting, or other pre-commit hooks.

Solution: Fix the hook violations (usually formatting). The skill runs the fix through formatters if detected. If the hook is unrelated to the change, investigate rather than bypassing with --no-verify.

---

File Mode Issues

Issue: Unrecognized Report Format

Symptom: File mode agent cannot parse the review report.

Cause: The report doesn't match expected formats (code-review skill template, generic markdown with file:line references).

Solution: The skill supports these formats:

• Code-review skill reports: ## Findings with **[Blocker]**, **[Improvement]** markers
• Generic markdown: numbered lists with file:line references
• Plain text: lines containing file paths and line numbers

If the format isn't recognized, the agent extracts whatever actionable items it can find and presents them for confirmation.

Issue: File Path Not Found

Symptom: Findings reference files that don't exist in the current working directory.

Cause: The review was generated from a different branch or the files have since been moved/deleted.

Solution: The skill checks each referenced file before verification. Missing files are flagged as "cannot verify" in the triage report. If many files are missing, it suggests checking out the correct branch.

---

Edge Cases

Issue: PR Closed During Resolution

Symptom: PR is closed or merged between Phase 1 and Phase 5.

Solution: The skill re-checks PR status before pushing (Phase 5). If closed, it informs the user and offers to keep the local commits for manual application.

Issue: Reviewer Deletes Comment

Symptom: A comment extracted in Phase 1 no longer exists in Phase 5.

Solution: Skip the reply for that comment. The fix is still valid — it was verified against the code, not just the comment.

Issue: Branch Protection Prevents Push

Symptom: git push fails due to branch protection rules (required reviews, status checks).

Solution: The skill cannot bypass branch protection. It informs the user and suggests: 1. Push to a separate branch and create a follow-up PR 2. Ask a repository admin to temporarily adjust protection rules 3. Push with --force-with-lease if the protection only requires linear history

---

Getting Help

• GitHub CLI docs
• GitHub REST API — Pull Request Comments
• GitHub REST API — Issue Comments
• File issues at the plugin repository

PR Issue Resolver: Detailed Workflow

Detailed methodology for multi-agent review resolution, including agent prompt templates, scoring rubric, and reply formats.

For quick start instructions, see SKILL.md.

---

Input Mode Detection

PR Mode

Detect when $ARGUMENTS is a PR number or URL:

123                                    → PR number
https://github.com/org/repo/pull/123   → extract PR number from URL
gh pr view 123                         → verify PR exists

Required: gh auth status must succeed with repo access.

File Mode

Detect when $ARGUMENTS is a file path:

reviews/code/2026-03-18_code-review.md → relative path
/absolute/path/to/review.md            → absolute path
./review-report.md                     → current directory

Verify the file exists with Read tool. Parse findings from the report.

Supported report formats:

• Code-review skill reports (review/skills/code-review/ template): look for ## Findings section with **[Blocker]**, **[Improvement]**, **[Question]** markers
• Generic markdown: look for numbered/bulleted lists with file:line references
• Plain text: extract actionable items with file references

---

Phase 1 — Agent Prompt Templates

Agent A — PR Metadata (Haiku)

You are extracting PR metadata for review resolution.

Run these commands and return a structured summary:

1. PR details:
   gh pr view {number} --json number,title,body,baseRefName,headRefName,state,author,reviewRequests,statusCheckRollup

2. Diff (file names only for overview):
   gh pr diff {number} --name-only

3. Full diff (for verification context):
   gh pr diff {number}

Return:
- PR title and description summary
- Base and head branches
- Author
- CI status: pass/fail/pending/none
- Files changed (list)
- Review requestees (who needs to re-approve)

Agent B — Comment Extraction (Haiku)

You are extracting all review comments from a GitHub PR for resolution.

Fetch comments from BOTH endpoints (they are different):

1. Inline review comments (attached to specific code lines):
   gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate

2. General issue comments (not attached to code):
   gh api repos/{owner}/{repo}/issues/{number}/comments --paginate

For each comment, extract:
- id: the comment ID (needed for replies)
- author: who wrote it
- type: "inline" or "general"
- file: file path (inline only)
- line: line number (inline only)
- body: full comment text
- resolved: true/false (check if the review thread is resolved)
- has_suggestion: true if body contains a ```suggestion code block
- created_at: timestamp

Filter OUT:
- Comments by the PR author (self-comments)
- Bot comments (CI status, coverage reports)
- Already-resolved threads
- Pure approval comments ("LGTM", "Looks good", thumbs up)

Return: structured JSON-like list of actionable comments, sorted by file path.

File Mode Agent (Haiku)

You are parsing a code review report file to extract actionable findings.

Read the file and extract each finding with:
- description: what the issue is
- file: file path referenced
- line: line number (if available)
- category: Blocker / Improvement / Question / Nit (from report markers)
- suggested_fix: code suggestion (if provided)
- source: which reviewer/category found it (if available)

Skip:
- Praise items
- Informational notes without actionable suggestions
- Summary/metadata sections

Return: structured list of actionable findings.

---

Phase 2 — Verification Agent Template

Sonnet Verification Agent

Each verification agent receives one comment/finding and returns a verdict.

You are verifying a review comment against the actual codebase.

REVIEW COMMENT:
{comment body}

REFERENCED FILE (50 lines of context):
{file content around the referenced line}

PR DIFF (or branch diff):
{relevant diff section}

PR DESCRIPTION:
{PR title and body summary}

YOUR TASK:
1. Read the actual code — do NOT rely solely on the comment's claims
2. Determine if the issue described actually exists in the code
3. Check if the suggestion would actually improve the code
4. Consider whether the current approach might be intentional

RETURN (all fields required):
Verdict: CONFIRMED | FALSE-POSITIVE | AMBIGUOUS
Category: Blocker | Bug | Code Quality | Style | Question
Confidence: 0-100 (see rubric below)
Evidence: What you checked and what you found. Be specific — cite code lines.
Suggested resolution: Either a specific code change, a response to post, or options if ambiguous.

FALSE POSITIVE INDICATORS (skip these):
- Reviewer misunderstood the code or missed surrounding context
- Concern is handled by the framework (e.g., XSS in React, CSRF in Rails)
- Suggestion contradicts established codebase patterns
- Issue is pre-existing and not introduced by this PR
- Concern is purely stylistic with no functional impact
- Reviewer's suggestion would actually introduce a bug
- The "issue" is a deliberate design choice documented in comments

AMBIGUOUS INDICATORS (mark as AMBIGUOUS, not FALSE-POSITIVE):
- Multiple valid approaches exist
- Best practice is genuinely debatable
- Reviewer and code author may have different valid perspectives
- Performance trade-off with no clear winner

CONFIDENCE RUBRIC:
- 0-24: False positive — doesn't hold up to code inspection
- 25-49: Plausible concern but likely misunderstanding
- 50-74: Valid observation but minor or nitpick
- 75-89: Real issue, important, impacts functionality
- 90-100: Critical — confirmed bug, security hole, or data loss risk

Batching Strategy

For PRs with many comments (>5):

• Batch verification agents into groups of 5
• Launch each batch in parallel
• Wait for batch to complete before launching next
• This prevents overwhelming the system with too many concurrent agents

For PRs with 5 or fewer comments, launch all agents in parallel.

---

Comment Categorization Taxonomy

---

False Positive Filtering Rules

Apply before including any finding in the triage report.

Hard Exclusions

1. Reviewer misread the code: The concern describes behavior that doesn't match what the code actually does 2. Framework-handled: The concern is addressed by the framework's built-in protections (React XSS, Django CSRF, Spring Security) 3. Already addressed: The code already handles the concern in a way the reviewer missed (e.g., validation happens upstream) 4. Pre-existing: The issue exists on unchanged lines and was not introduced by this PR 5. Codebase convention: The code follows an established pattern used elsewhere in the project 6. Linter territory: Formatting, import order, whitespace — defer to automated tools 7. Intentional choice: Comments or commit messages indicate the approach was deliberate

Signal Quality Check

For remaining findings, verify: 1. Is there a concrete, demonstrable impact? 2. Is the suggestion actionable with a specific fix? 3. Would a senior engineer confidently raise this?

If any answer is "no," lower the confidence score accordingly.

---

Confidence Scoring — Detailed Rubric

Threshold: Filter out all findings scoring below 80.

If a verification agent fails (timeout, error), default the finding's score to 80 (conservative — keep it in the report rather than silently dropping a potential real issue).

---

Triage Report Template

## Review Issue Triage — {owner}/{repo} PR #{number}
{N} comments analyzed | {M} actionable (threshold: 80) | {K} false positives filtered

### CONFIRMED ({count})
| # | Author | File:Line | Category | Confidence | Recommended Action |
|---|--------|-----------|----------|------------|-------------------|
| 1 | @reviewer | src/auth.ts:45 | Bug | 92 | Fix: add null check before access |
| 2 | @reviewer | src/api.ts:12 | Code Quality | 85 | Refactor: extract validation |

### FALSE POSITIVE ({count})
| # | Author | File:Line | Confidence | Reason |
|---|--------|-----------|------------|--------|
| 3 | @reviewer | src/db.ts:33 | 15 | Handled by ORM validation layer |

### AMBIGUOUS ({count})
| # | Author | File:Line | Options |
|---|--------|-----------|---------|
| 4 | @reviewer | src/config.ts:78 | A: Use env var / B: Keep hardcoded default |

### QUESTIONS ({count})
| # | Author | Comment | Suggested Response |
|---|--------|---------|-------------------|
| 5 | @reviewer | "Why not use X here?" | Explain: Y was chosen because... |

---
**Next step**: Approve this plan to proceed with fixes, or modify individual items.

---

Resolution Planning

Priority Ordering

Apply fixes in this order to minimize cascading issues:

1. Blockers — security, crashes, data loss 2. Bugs — logic errors, null handling 3. Code Quality — refactoring, performance 4. Style — naming, formatting 5. Questions — respond with explanations

Edge Cases

Conflicting suggestions: Two reviewers suggest different approaches.

• Mark as AMBIGUOUS
• Present both options with pros/cons
• Let user decide before implementing
• If reviewers are available, suggest asking for consensus in a thread

Regression risk: A fix would solve one issue but break another.

• Flag in the triage report: "Warning: this fix may affect [related functionality]"
• Suggest mitigations (additional tests, guard clauses)
• Let user decide whether the trade-off is acceptable

Out-of-scope suggestions: Valid but unrelated to this PR.

• Acknowledge the suggestion
• Create a follow-up issue: gh issue create --title "..." --body "Identified during PR #X review"
• Reply with: "Valid suggestion — created follow-up issue #Y"

Multiple options offered: Reviewer suggests "Option A: ... or Option B: ...".

• Present all options to the user
• Do NOT choose autonomously
• Include pros/cons for each if available

Reviewer unavailable: Need clarification but reviewer is unresponsive.

• Document your interpretation in the reply
• Proceed with the safest approach
• Note: "Proceeding with [approach] based on [reasoning]. Happy to adjust if you had something else in mind."

Commit Message Format

fix(scope): brief description — addresses review comment on [topic]

Examples:

fix(auth): validate token expiry before access — addresses review comment on null handling
fix(api): add rate limit headers to response — addresses review comment on missing headers
refactor(db): extract query builder — addresses review comment on code duplication

One commit per fix. Reference the review comment topic, not the comment ID (IDs are opaque to readers).

---

Comment Reply Formats

Inline Review Comments (Code-Level)

Reply in-thread using the GitHub API:

gh api repos/{owner}/{repo}/pulls/{pr}/comments/{comment_id}/replies \
  -f body="Addressed in commit \`abc1234\` — added null check before token access.

The validation now throws early if the token is expired, preventing the downstream NPE."

General PR Comments (Issue-Level)

GitHub issue comments do NOT support threading. Post a single consolidated response with anchor links:

Thanks for the thorough review! Here's the resolution for each item:

### Re: [Null check on token](#issuecomment-12345)
Addressed in commit `abc1234` — added validation before access.

### Re: [Rate limit headers](#issuecomment-12346)
Addressed in commit `def5678` — added X-RateLimit-* headers to all API responses.

### Re: [Extract query builder](#issuecomment-12347)
Created follow-up issue #89 — valid suggestion but out of scope for this PR.

### Re: [Why not use Redis here?](#issuecomment-12348)
We chose PostgreSQL advisory locks because [reason]. The trade-off is [X] but it avoids [Y]. Happy to discuss further.

False Positive Reply Template

Thanks for flagging this. I investigated and this is actually handled by [specific mechanism]:

- [Evidence: code trace, test output, or documentation reference]
- [Why the current approach is correct]

Let me know if I'm missing something.

Deferred Reply Template

Valid suggestion — I've created follow-up issue #{number} to track this.

This is out of scope for the current PR because [reason], but it's worth addressing separately.

---

Research for Ambiguous Suggestions

When a suggestion is marked AMBIGUOUS and involves debatable patterns:

1. Use /core:research to investigate best practices:

   /core:research [topic — e.g., "error handling patterns in TypeScript async functions"]

2. Research when:

• Multiple valid solutions exist and you're unsure which is best
• Reviewer and author disagree on approach
• You're unfamiliar with a suggested library, API, or pattern
• The suggestion involves architecture or design decisions

3. Include research findings in the PR comment:

   I researched this and found that [finding]. Based on [source/pattern],
   I went with [approach] because [reasoning]. The alternative ([other approach])
   would [trade-off].

---

Phase Transition Logic

• Phase 1 → Phase 2: Wait for all Phase 1 agents. If zero actionable comments, report "Nothing to resolve" and stop.
• Phase 2 → Phase 3: Collect all verdicts. Deduplicate: if two findings reference the same file:line, merge them. If all agents fail, fall back to manual sequential verification.
• Phase 3 → Phase 4: User must explicitly approve the plan. Do not proceed without approval.
• Phase 4 → Phase 5: After all approved changes are committed, push and reply. If tests fail on any fix, stop and report — do not push broken code.
• File mode: Skip Phase 5 entirely (no PR to update). Optionally commit fixes to the current branch.

Error Handling

• Agent timeout: Continue with results from successful agents. Note in report: "Note: verification for comment #{id} did not complete."
• All agents fail: Fall back to sequential verification — read the code yourself and assess each comment directly.
• gh CLI failure: Check gh auth status. If rate-limited, wait and retry. If permission denied, inform the user.
• Merge conflict on push: Rebase the branch and retry. If conflicts persist, inform the user.