pr-feedback-handler git:20261020.f79b691A

Immutable. This exact content never changes and is served at /api/v1/blob/ed4e336a27f07bd9.

---
name: pr-feedback-handler
description: Handles Pull Request comments by either fixing issues or replying with reasons. Use when PR receives comments that need addressing. Analyzes each comment and decides whether to (A) implement the fix or (B) reply explaining why not. Triggers after PR comments arrive (typically 3+ minutes after PR opened).
---
# PR Feedback Handler

Processes PR comments and takes appropriate action: fix or reply.

## Workflow

### Step 1: Fetch Comments

```bash
# Get all PR comments with context
gh pr view <branch> --json comments,reviews --jq '{
  comments: [.comments[] | {author: .author.login, body: .body, createdAt: .createdAt}],
  reviews: [.reviews[] | {author: .author.login, body: .body, state: .state}]
}'

# Inline review comments (not available via gh pr view)
gh api "repos/{owner}/{repo}/pulls/<pr-number>/comments" --paginate \
  --jq '.[] | {author: .user.login, path: .path, line: .line, body: .body, in_reply_to_id: .in_reply_to_id}'
```

### Step 2: Analyze Each Comment

For every comment, determine:

**Type A: Fix Required**

- Bug reports
- Code style violations
- Missing tests
- Security issues
- Performance problems
- Logic errors

**Type B: Reply With Reason**

- Design decisions already discussed
- Out of scope for this PR
- Intentional trade-offs
- Already addressed elsewhere
- False positives

### Step 3: Execute Actions

#### For Type A (Fix):

```bash
cd <worktree-path>

# The worktree is already on the PR branch — verify, never switch:
current=$(git rev-parse --abbrev-ref HEAD)
[ "$current" = "<branch-name>" ] || { echo "Wrong worktree: on $current"; exit 1; }

# Implement fix based on comment
# <edit files per comment instructions>

# Test the fix — detect the project's runner
if [ -f package.json ]; then
  if [ -f pnpm-lock.yaml ]; then pnpm test
  elif [ -f yarn.lock ]; then yarn test
  elif [ -f bun.lockb ] || [ -f bun.lock ]; then bun test
  else npm test; fi
elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then pytest
elif [ -f go.mod ]; then go test ./...
else echo "No test runner detected — report to the orchestrator before committing"; fi

# Commit with reference to comment
git add <files-changed-by-this-fix>   # never `git add .`
git diff --cached --stat   # confirm only intended files
git commit -m "Fix: <brief description>

Addressing feedback from @<commenter>
- <specific change made>

Refs: PR #<number>"

# Push update
git push origin <branch-name>
```

#### For Type B (Reply):

```bash
# Post reply comment
gh pr comment <pr-number> --body "@$(cat <<'EOF'
<commenter> <reasoning>

<explanation of why this approach was chosen>

<context or trade-off details>
EOF
)"

# To reply in-thread instead, use the GraphQL API:
# gh api graphql -f query='mutation($id: ID!, $body: String!) {
#   addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$id, body:$body}) { comment { url } } }' \
#   -F id="<THREAD_NODE_ID>" -f body="@user<reply>"
```

### Step 4: Resolve Thread (if applicable)

```bash
gh api graphql -f query='
mutation($id: ID!) { resolveReviewThread(input: {threadId: $id}) { thread { isResolved } } } }' \
  -F id="<THREAD_NODE_ID>"
```

### Step 5: Check for More Comments

```bash
# After processing, check if new comments arrived
gh pr view <branch> --json comments --jq '.comments | length'
```

### Step 6: Report to the Orchestrating Agent

Return structured result:

```
PR Feedback Processed:
- PR: <URL>
- Comments received: <N>
- Actions taken:
  - Fixed: <N> issues (commits pushed)
  - Replied: <N> comments (reasons provided)
- Status: <resolved/pending/awaiting-reviewer>

Next steps:
- Monitor for additional comments
- Await reviewer re-review
- The orchestrating agent will continue monitoring
```

## Decision Matrix

| Comment Type | Action | Example |
| --- | --- | --- |
| "This breaks tests" | Fix | Run tests, identify failure, fix code |
| "Missing validation" | Fix | Add validation logic + tests |
| "Use early return" | Fix | Refactor code structure |
| "Why not use X pattern?" | Reply | Explain pattern choice, trade-offs |
| "Add Y feature here" | Reply | "Out of scope - tracked in TASK-Z" |
| "Security issue: Z" | Fix | Immediate fix + security review |
| "Formatting" | Fix | Apply linter/auto-format |
| "I don't understand..." | Reply | Clarify with code comments + reply |

## Comment Analysis Heuristics

**Keywords indicating FIX needed:**

- "bug", "error", "fails", "broken", "crash"
- "should be", "needs to", "must", "missing"
- "security", "vulnerability", "exploit"
- "test", "coverage", "spec"

**Keywords indicating REPLY:**

- "why", "consider", "what if", "suggestion"
- "nit", "optional", "thought"
- "out of scope", "future", "separate PR"

Comments marked "nit" or "optional" are **Type B (Reply)** unless the reviewer
explicitly asked for a specific mechanical fix.

## Error Handling

**If fix conflicts with the base branch:**

- Fetch and merge the base branch: `git fetch origin && git merge origin/<default-branch>`
  (resolve conflicts, re-run tests, then `git push origin <branch-name>`)

**If comment is unclear:**

- Reply asking for clarification
- Document unclear comment for the orchestrating agent
- Do NOT guess - get clarity first

**If fix requires major refactor:**

- Reply with estimate and trade-offs
- Ask if commenter prefers:
    1. Fix in this PR (larger scope)
    2. Separate PR (tracked as new task)

## Integration

**Called by:**

- The orchestrating agent when comments detected
- pr-opener workflow (after 3 min wait)
- Scheduled monitoring job

**Calls to:**

- Worktree for edits (same location as original)
- GitHub CLI for comments

**Reports to:**

- The orchestrating agent for workflow status

## References

- [Acceptance Criteria](references/acceptance-criteria.md) - Classification rules, commit/reply formats, error-handling scenarios
- [Best Practices](references/best-practices.md) - Decision tree, reply templates, tone guidance