Resolve PR Comments in Parallel (v3)

DEFAULT WORKFLOW for resolving PR comments with parallel execution.

MANDATORY: Background Execution

The ENTIRE workflow (Phases 0-6) MUST run as a background agent. This prevents the workflow from being sidetracked by user questions, CI failures, or context switches.

Foreground steps (do these FIRST, before launching the agent):

1. Detect PR number from args, current branch, or ask user
2. Print: "Launching PR resolution for #$PR_NUM in background. You'll be notified when it completes."
3. Launch background agent with the full workflow:

Agent(
  run_in_background: true,
  prompt: "You are resolving PR comments for PR #$PR_NUM.

Read the pr-resolution skill at ~/.claude/skills/pr-resolution/SKILL.md and execute Phases 0-6.

IMPORTANT:
- For questions classified as [question] that need human input, skip them and note them in your final output
- For CI failures, fix them as part of the workflow — do NOT stop or ask for help
- Complete ALL phases including the shepherd launch in Phase 6
- Your final output should summarize: comments resolved, comments skipped (with reasons), CI status"
)

That's it for the foreground. Everything below is executed by the background agent.

Quick Reference

Workflow Overview

Phase 0: Pre-Flight     → GoodToGo status check (if installed, otherwise skip)
Phase 1: Discovery      → Gather comments, parse bot formats, enumerate
Phase 2: Classification → Categorize by priority, group by file
Phase 3: Resolution     → Launch parallel agents by file group
Phase 4: Verification   → Local checks + GoodToGo gate (if installed)
Phase 5: Completion     → Commit, push, resolve threads
Phase 6: Shepherd       → Background agent monitors for new bot comments

Phase 0: Pre-Flight

If gtg is installed, run the GoodToGo pre-flight check (see references/goodtogo.md):

if command -v gtg &> /dev/null; then
  # gtg auto-detects repo from git remote
  GTG_RESULT=$(gtg $PR_NUM --format json 2>/dev/null)
  GTG_STATUS=$(echo "$GTG_RESULT" | jq -r '.status')
fi

Route based on status (or skip straight to Phase 1 if gtg is not installed):

• READY → Quick verify and commit (fast path — skip Phases 1-3)
• CI_FAILING → Fix CI first
• ACTION_REQUIRED → Continue with full workflow
• UNRESOLVED_THREADS → Continue with full workflow

Phase 1: Discovery

1. Gather comments using scripts from references/discovery.md
2. Parse bot formats using rules from references/bot-formats.md
3. Print enumeration - counts MUST match before proceeding

Phase 2: Classification & Grouping

1. Classify each comment using references/classification.md
2. Group by file for parallel execution:

## Parallel Execution Plan

### Group A: src/api/route.ts (3 comments → 1 agent)
- #1 [blocking] Line 45 - Add error handling
- #3 [suggestion] Line 67 - Improve validation

### Group B: src/components/Button.tsx (1 comment → 1 agent)
- #2 [suggestion] Line 23 - Add prop types

### Group C: CI Failures (if any → 1 agent)
- Fix lint/type errors

Total: 3 parallel agents

Phase 3: PARALLEL EXECUTION

MANDATORY: Launch agents simultaneously using the Task tool:

Agent 1: "Fix comments on src/api/route.ts"
- Comment #1: Add error handling at line 45
- Comment #3: Improve validation at line 67

Agent 2: "Fix comments on src/components/Button.tsx"
- Comment #2: Add prop types at line 23

Agent 3: "Fix CI failures"
- Lint errors
- Type errors

Parallel execution rules:

Wait for all agents to complete.

Phase 4: Verification Gate (MANDATORY)

1. Run local checks from references/verification.md
2. If gtg is installed, run final verification from references/goodtogo.md (deterministic READY/BLOCK signal)
3. Verify all resolutions - every comment needs explicit resolution

DO NOT commit until all checks pass.

Phase 5: Completion (MANDATORY — DO NOT SKIP)

Follow steps from references/completion.md:

5a. Commit

1. Commit all fixes together

5b. Capture timestamp (for shepherd)

2. Capture the current UTC timestamp immediately before push:

LAST_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

5c. Push

3. Push to remote
   • If push fails: Skip Phase 6 (shepherd). The resolution is incomplete.

5d. Post resolution summary

4. Post resolution summary comment to PR

5e. Resolve ALL GitHub threads (MANDATORY)

Run the resolve-all-threads script:

~/.claude/skills/pr-resolution/bin/resolve-all-threads $PR_NUM

This script:

• Queries all unresolved threads on the PR
• Resolves each one via GraphQL mutation
• Verifies zero unresolved threads remain

If the script reports failures or remaining threads: DO NOT mark workflow as complete. Fix manually with bin/resolve-pr-thread THREAD_ID.

5f. Final verification

5. Confirm script output shows "All threads resolved"

Workflow is NOT complete until all threads are resolved.

Phase 6: Shepherd (Automatic)

After Phase 5 verification passes, launch the shepherd as a background agent to monitor for new bot comments.

This phase runs automatically. Do not skip it. Do not ask the user.

1. Capture context:

OWNER_REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
BRANCH=$(git branch --show-current)
RUN_ID=$(date +%s)

2. Launch background agent:

Agent(
  run_in_background: true,
  prompt: "Read skills/pr-resolution/shepherd.md and follow it.

    Context:
    {\"PR_NUM\": $PR_NUM, \"LAST_TIMESTAMP\": \"$LAST_TIMESTAMP\", \"OWNER_REPO\": \"$OWNER_REPO\", \"BRANCH\": \"$BRANCH\", \"RUN_ID\": \"$RUN_ID\"}"
)

3. Print: "Shepherd monitoring PR #$PR_NUM in background. You'll be notified when it completes."

If agent launch fails: Print the error and exit cleanly. The initial resolution is already complete.

This phase is NOT re-entered during shepherd RE_RESOLVE iterations.

Example: PR with 6 Comments

## Discovery
1. [blocking] src/api/route.ts:45 - Security issue
2. [suggestion] src/api/route.ts:67 - Add validation
3. [suggestion] src/components/Form.tsx:23 - Add types
4. [nitpick] src/utils/format.ts:12 - Typo
5. [question] src/lib/auth.ts:89 - "Handle null?"
6. CI: Lint error

## Parallel Plan (after asking human about #5)
- Agent 1: src/api/route.ts (#1, #2)
- Agent 2: src/components/Form.tsx (#3)
- Agent 3: src/utils/format.ts (#4)
- Agent 4: src/lib/auth.ts (#5 - if fix)
- Agent 5: CI fix (#6)

## Execution
Launch agents in parallel → Wait → Verify → Commit → Push

Related