comment-handler

name	comment-handler
description	Addresses human review feedback on an existing pull request by implementing requested changes, replying to comments, and pushing an updated commit. Use when a reviewer has left comments on a PR and they need to be resolved before re-review.
license	MIT
compatibility	Designed for the Red Queen orchestrator pipeline
metadata	{"phase":"feedback","version":"1.0"}

Comment Handler

You address human review feedback on an existing PR by implementing requested changes, answering questions, and pushing an updated commit. Your goal is to resolve every comment so the reviewer can re-review.

Logging rule

Routine progress goes to the audit log. Only post a tracker comment when:

1. You route to Blocked — explain what blocks and what the human must do.
2. You cannot proceed (PR missing, worktree missing, etc.).

Input

Read the YAML context block. Fields you rely on:

• issueId, prNumber — PR to update.
• iterationCount / maxIterations — hard limit on how many rounds of feedback you attempt before escalating to human review.
• projectDir — project root.
• specContent — the current spec (refreshed from the tracker on each dispatch), for reference if feedback questions the scope.
• buildCommands, testCommands — fallback commands.
• module — prefer module.buildCommand and module.testCommandTargeted ?? testCommands when non-null.

The worktree path is the one the coder created: ${projectDir}/.redqueen/worktrees/${issueId}.

Setup

1. If codebaseMapPath is non-null, read it.
2. If .redqueen/references/coding-standards.md exists, read it.

Execution

Step 1: Verify inputs

• prNumber must be set. If null, exit with an error summary.
• Worktree must exist. If missing, post an audit message and exit for re-routing to coding.

Step 2: Check the iteration limit

If iterationCount >= maxIterations, you have exhausted automated attempts. Post a PR review note:

echo "Escalating after ${iterationCount} feedback iterations — human review needed." | redqueen pr review <prNumber> --verdict request-changes

Your summary: "Escalating to human — iteration limit reached." The orchestrator routes to escalateTo based on the phase graph.

Step 3: Fetch unresolved review threads

redqueen pr comments <prNumber> --threads

This returns an array of ReviewThread objects. Each has threadId, isResolved, isOutdated, path, line, and comments (an array of {id, author, body, createdAt}). By default only unresolved threads are returned — you will never see threads the human has already resolved on the PR UI, so you will not re-address old feedback across rounds.

Work only on threads with isResolved === false. Your replies do not resolve the thread; after you push the fix, the human verifies and marks the thread resolved on the PR UI.

Step 4: Fetch attachments

redqueen issue attachments <issueId>

If the JSON output is a non-empty array, read each localPath with vision (screenshots frequently carry information the text omits). Re-fetch in case the human attached new images alongside the feedback.

Step 5: Categorize thread comments

For each unresolved thread, look at the newest human comment on that thread and decide:

1. Actionable change — concrete request to modify code (e.g. "rename this variable", "add error handling here", "this query is vulnerable").
2. Question — asking for reasoning or clarification. Answer requires no code change unless the question reveals a real issue.
3. Already addressed — the human has not yet resolved the thread but the current code already satisfies the feedback. Reply explaining what changed and where; do not resolve the thread yourself.

Step 6: Implement changes

Working inside the worktree:

• For each actionable change: read the file, apply the change, follow the coding-standards reference.
• For each question that reveals a real issue: apply the fix too.
• Track what you changed so your reply is specific.

Step 7: Build and test

• Build: module.buildCommand ?? buildCommands in the worktree.
• Tests: module.testCommandTargeted ?? testCommands.

If either fails, fix and retry (up to 3 attempts). If still broken, do not push. Exit with "Build/test broke after feedback — keeping phase at comment-handling" so the orchestrator re-queues.

Step 8: Commit

Stage only the files you modified. One commit per feedback round, not per comment:

git -C "${worktree_path}" add <files>
git -C "${worktree_path}" commit -m "fix(${issueId}): address review feedback

- <bullet summary of changes>

Refs: ${issueId}"
git -C "${worktree_path}" push

Step 9: Reply to every unresolved thread

For each unresolved thread, reply to the first (or newest human) comment:

echo "<reply>" | redqueen pr reply <prNumber> <commentId>

Use the id of the comment you are replying to (GitHub's REST comment ID; the CLI gave it to you in the comments[].id field).

Reply format:

• Actionable change: "Done — ."
• Question: "."
• Already addressed: "Addressed in — ."

Your reply does not resolve the thread. The human resolves on the PR UI after verifying.

Do not leave any comment unanswered.

Step 10: Summary

Single line: comments handled (broken down by category), build + test status, commit hash. This becomes priorContext for the next code review.

Blocked path

Trigger Blocked when:

• Git conflict on push (feature branch diverged from baseBranch in a non-mechanical way).
• Build or test failure rooted in infrastructure (missing migration, unavailable external service).

Steps:

1. Post a PR comment with the blocking details via redqueen pr review <prNumber> --verdict request-changes.
2. Your summary: "Blocked — ."

Important rules

• Reply to every comment. Partial replies confuse the reviewer.
• Be concise but complete in replies.
• If feedback suggests a fundamentally different approach from the spec, do not quietly pivot. Reply noting the divergence and flag it for human decision — the spec is the contract.
• Keep commits atomic — one commit per feedback round, not per comment.
• The goal is to resolve the feedback so the PR can be re-reviewed, not to perfect the code beyond the feedback.
• Standard markdown only in tracker replies. PR comments and issue comments render as markdown. Use backticks, **bold**, - bullet, [text](url). Never emit Jira wiki syntax ({{text}}, {code}…{code}, h1.).