Pr Patrol

PR Patrol

Process automated PR review comments through a 7-gate workflow with phase-based loading.

⚠️ CRITICAL REMINDERS

1. READ PHASE FILE FIRST - Check status in state file, read phases/gate-{N}.md for current phase
2. USE AGENTS FOR VALIDATION - Use bot-comment-validator via Task tool, never manual
3. ASK ABOUT PR-REVIEW AGENTS - After checks pass, ask about code-reviewer/silent-failure-hunter
4. ISSUE COMMENTS NEED @MENTION - GitHub issue comments don't support threading
5. UPDATE STATE FILE - After EVERY action (use scripts/update_state.sh)
6. NEVER REPLY TO COPILOT - Silent fix only, no reactions, no replies
7. TRUST SCRIPT OUTPUT - When scripts return data, DO NOT make extra API calls to "verify"!

Quick Reference

Ignored: vercel[bot], dependabot[bot], renovate[bot], github-actions[bot]

Workflow Diagram

/pr-patrol [PR#]
       │
       ▼
┌─ GATE 0: Init ──────────────────────┐
│ [AskUserQuestion] Mode, scope       │ → phases/gate-0-init.md
└─────────────────────────────────────┘
       │
       ▼
┌─ GATE 1: Collect ───────────────────┐
│ [AskUserQuestion] Proceed?          │ → phases/gate-1-collect.md
└─────────────────────────────────────┘
       │
       ▼
┌─ GATE 2: Validate ──────────────────┐
│ [Task: bot-comment-validator]       │ → phases/gate-2-validate.md
│ [AskUserQuestion] Which to fix?     │
└─────────────────────────────────────┘
       │
       ▼
┌─ GATE 3: Fix & Check ───────────────┐
│ Apply fixes → typecheck → lint      │ → phases/gate-3-fix.md
│ [AskUserQuestion] Run pr-review?    │ ← Gate 3.5!
└─────────────────────────────────────┘
       │
       ▼
┌─ GATE 4: Commit ────────────────────┐
│ [AskUserQuestion] Review & commit?  │ → phases/gate-4-commit.md
└─────────────────────────────────────┘
       │
       ▼
┌─ GATE 5: Reply ─────────────────────┐
│ [AskUserQuestion] Post replies?     │ → phases/gate-5-reply.md
│ Also read: bot-formats.md           │
└─────────────────────────────────────┘
       │
       ▼
┌─ GATE 6: Push ──────────────────────┐
│ [AskUserQuestion] Push? Cycle 2?    │ → phases/gate-6-push.md
└─────────────────────────────────────┘

Phase Routing (FOLLOW THIS!)

Step 1: Check State File

STATE_FILE=".claude/bot-reviews/PR-{N}.md"

Step 2: Read Current Phase

Step 3: Follow Phase Instructions

Each phase file contains:

• Detailed step-by-step actions
• MANDATORY AskUserQuestion prompts
• Edge cases and error handling
• State file update commands

Scripts Location

SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/pr-patrol/scripts"

# Core scripts
"$SCRIPTS/fetch_pr_comments.sh" owner repo pr    # Parallel API fetch
"$SCRIPTS/detect_thread_states.sh"               # State detection
"$SCRIPTS/check_new_comments.sh" owner repo pr   # New since push
"$SCRIPTS/check_reply_status.sh" owner repo pr   # Reply tracking
"$SCRIPTS/update_state.sh" file field value      # State updates

Reference Files Location

SKILL_ROOT="${CLAUDE_PLUGIN_ROOT}/skills/pr-patrol"

# Read these files with their FULL paths:
"$SKILL_ROOT/phases/gate-{N}.md"    # Phase instructions
"$SKILL_ROOT/bot-formats.md"        # Bot protocols (CRITICAL for Gate 5!)
"$SKILL_ROOT/templates.md"          # Reply templates

Critical Rules

1. EVERY gate requires AskUserQuestion - Never skip user approval
2. ALL comments must be validated - Severity only affects priority
3. Copilot gets NO response - Silent fix only, no reactions, no replies
4. NEVER commit/push without approval - Explicit consent required
5. NEVER force push - Blocked completely
6. Typecheck/lint are MANDATORY - Block on failure
7. ALWAYS use --paginate - Default GitHub API returns only 30 comments
8. Fetch BOTH endpoints - Review comments (/pulls/{pr}/comments) AND issue comments (/issues/{pr}/comments)
9. Extract embedded CodeRabbit comments - Use parse_coderabbit_embedded.sh for nitpicks, duplicates, outside-diff
10. Issue vs PR review comments - Different reply methods! Issue comments need @mention (no threading)
11. Reaction BEFORE reply - For Greptile/Codex/Sentry, add reaction first, then reply
12. Short reply format - "Fixed in commit {sha}: {description}" NOT verbose essays
13. Use helper scripts - ${CLAUDE_PLUGIN_ROOT}/skills/pr-patrol/scripts/ has utilities
14. TRUST SCRIPT OUTPUT - When scripts return data, DO NOT make verification queries

jq Escaping Warning

CRITICAL: Shell escaping corrupts jq operators. This affects:

• Direct jq commands
• gh api --jq flag
• Any inline jq in bash

Forbidden Patterns

# ❌ WRONG - "!=" gets escaped to "\!=" → "unexpected token" error
jq '[.[] | select(.field != null)]'
gh api ... --jq '[.[] | select(.in_reply_to_id != null)]'

# ❌ WRONG - Same issue with "not null"
jq 'select(.x != "value")'

Safe Alternatives

# ✅ CORRECT - Use truthy check (implicit null filter)
jq '[.[] | select(.field)]'

# ✅ CORRECT - Use "| not" for negation
jq '[.[] | select(.bot == "Copilot" | not)]'

# ✅ CORRECT - Use external .jq file for complex queries
jq -f "$SCRIPT_DIR/filter.jq"

Rule: For any jq with != or complex logic, use the scripts in scripts/ instead of inline jq.