Interactive Pr Review

Interactive PR Review

Run a review as a user-guided conversation. Findings ultimately become inline comments in one complete GitHub review, never independently published comments. When the user chooses Finish the review and prepare the selected comments for publication, create one editable GitHub pending review containing the selected comments and an unsubmitted summary. Do not submit that review until the user explicitly instructs publication.

Maintain Review State

Keep a compact private state record throughout the review:

• PR URL/number, repository, base SHA, and reviewed head SHA;
• each finding's stable ID and status (queued, withdrawn, skipped, or published);
• for every queued inline comment: path, line or range, side, and head SHA that anchors it;
• comment-set approval, selected verdict, approved summary, and pending-review URL when applicable.

Preserve this state when adopting or resuming a review. Never reuse an ID. Treat published comments as history and do not duplicate them.

Adopt an Ongoing Review

Allow explicit invocation at any point, for example: Use $interactive-pr-review from here. Preserve the target and useful context. Reconstruct the state from the conversation and GitHub: reported findings and evidence, unpublished drafts, withdrawn findings, published comments, and any pending review.

Briefly confirm the adopted queue, then enter the discussion loop. If no finding remains, offer Add a finding, Approve the PR with no feedback, and Finish without publishing feedback.

Review

1. Identify the target PR. Prefer configured GitHub MCP tools and fall back to gh only when unavailable. Read the repository agent rules, including agent.local.md, before drafting publication-ready comments.
2. Establish complete context: title, description, every current PR comment, review, and review thread (including resolved and outdated threads), current head SHA, and CI/check state. Consider changed-code comments stale but retain them as context.
3. Read each Jira ticket referenced in PR context before reviewing the diff, including every comment on the current Jira ticket. For each ticket, identify its Epic and read the entire Epic, every one of its subtickets, and their comments. Exception: when the current Jira ticket is a child of an EPIC that has more than 10 children, ask if we want to read all of them or just the current ticket and its direct epic. If any required ticket context or comments cannot be read, pause and ask whether to continue without the missing context or stop.
4. Inspect changed code, relevant callers, tests, existing threads, and checks comprehensively.
5. Report only actionable, evidence-backed findings. Review for both merge-blocking defects and worthwhile non-blocking improvements to the changed code. Queue a suggestion, chore, or nitpick only when it has a concrete benefit and an exact, actionable resolution; do not add feedback merely to avoid an empty review. Assign F1, F2, and so on. Do not prepare publication-ready comments yet.

When showing findings in the CLI, write for the person deciding whether to merge, not only for the person who knows the implementation. Use the badgeless Conventional Comments format. Never render badge Markdown, badge URLs, or a publication-ready comment body at this stage.

Lead with the concrete outcome in plain language. State the implementation detail only after explaining what can go wrong. Prefer short, familiar terms over project-internal names; define an unavoidable technical term in place. Use this finding shape:

F<n> · <label> (<decoration>) · path:line
What happens: <plain-language, observable outcome>
Failure flow:
1. <trigger>
2. <condition or behavior>
3. <error or incorrect outcome>
Why it matters: <user, operator, data, or business impact>
Suggested resolution: <concrete fix direction>
Evidence: <relevant caller, test, invariant, or condition; confidence when useful>

For example:

Failure flow:
1. A customer retries a timed-out payment.
2. The retry reaches this insert path.
3. The existing row violates the unique key.
4. The payment is reported as failed even though the first attempt may have succeeded.

Write a failure flow whenever the diff, relevant callers, tests, or invariants establish a credible path. Always render it as a multi-line Markdown numbered list, with one short sentence per step; never use an inline or arrow-separated flow. Include its trigger, important condition or state, the relevant behavior, and the resulting error or incorrect outcome. Keep it concrete and brief. Do not invent a flow for a merely theoretical concern; instead state the evidence and uncertainty plainly. Omit the flow when no meaningful runtime or user-action sequence applies.

Use the same Conventional Comments labels and optional decorations as the publication format, written as plain text (for example, F2 · issue (blocking) · src/Foo.php:42 · …). Omit the parentheses when no decoration applies. Format badges only when assembling the user-approved pending-review package.

Keep non-actionable observations separate and out of the publication queue. Do not treat a failing check as an inline code finding unless the PR caused it and a concrete code location and resolution are established. Record relevant failing checks as blockers or findings; describe unrelated/pre-existing failures as context; state when checks are unavailable.

Discussion Loop

Offer a structured choice after findings. Use runtime choice controls when available; otherwise use a short numbered list. While findings remain, include:

• Discuss F<n> for each queued finding;
• Add a finding;
• Withdraw F<n> for each unpublished finding;
• Finish the review and prepare the selected comments for publication;
• Finish without publishing feedback.

On Add a finding, inspect the concern and add it only if evidence supports an actionable concern. On Withdraw, state the reason, update state, exclude it from the review, and never reuse its ID. Published comments cannot be withdrawn; offer a corrective follow-up under the same publication gate.

When discussing a finding, validate assumptions and trade-offs, update severity or resolution when warranted, retain its ID, state its status, and return to the choice set. Do not manufacture feedback or publish because discussion appears complete.

When none remain, offer Add a finding, Approve the PR with no feedback, and Finish without publishing feedback. The no-findings approval is explicit authorization to publish one APPROVE review without inline comments. Re-read agent.local.md, confirm the head SHA has not changed, submit the standard summary, and confirm its URL. Do not require a pending-review gate in this path.

Pending Review and Publication Gate

Enter only when the user explicitly chooses Finish the review and prepare the selected comments for publication. Exclude withdrawn and skipped findings. One queued finding produces one inline comment unless the user asks to split it.

Before presenting the package, fetch the current head SHA. If it changed from the reviewed SHA, compare every queued finding with the new diff. Re-investigate only affected findings; re-anchor valid comments; withdraw or convert obsolete findings only with the user's agreement. Never use a stale line anchor.

Read references/conventional-comments-format.md before assembling any publication-ready inline comment outside swarm-agents mode.

Create the editable pending review immediately after the user chooses to finish the review. That choice authorizes writing the selected findings as one unsubmitted GitHub review; it does not authorize publication.

1. Assemble the complete package: destinations (path, line/range, side, head SHA), Markdown bodies, and a non-empty ## Review summary. Preserve each finding's plain-language outcome, impact, and evidence-backed failure flow in its comment, following references/conventional-comments-format.md. Keep the pending summary verdict-neutral unless the user has already selected a publication event; do not infer a new verdict from previous submitted reviews.
2. Refetch the head SHA immediately before creation and re-run the affected-finding check if it changed.
3. Detect a pending review authored by the current user. Never overwrite it blindly: show its state and, with the user's agreement, reuse/update it; otherwise stop rather than create a duplicate.
4. Create (or update with the user's agreement) one pending review in a single operation with the complete summary and every selected inline comment. Prefer GitHub MCP tools; fall back to gh only when necessary. Confirm its pending-review URL and contents.
5. Offer numbered next actions: Publish the review, Change the pending review, or Discard/finish without publishing. Apply requested changes to the same pending review and keep it unsubmitted.
6. On an explicit publication instruction, choose the event from the selected findings without a further verdict prompt: submit REQUEST_CHANGES when at least one queued comment is blocking; otherwise submit APPROVE. An explicit user-selected event overrides this default. Immediately before submission, refetch the head SHA. If it changed, do not submit. Re-run the affected-finding check; if any comment or summary needs to change, update the pending review and show the revised content. Otherwise submit the pending review using the selected event, then confirm its URL.

Review Summary

The summary is the concise decision record, not a standalone finding. Do not badge it.

• For Request changes, state that the PR is not ready to merge, summarize remaining blocker themes in one or two bullets, and point to the inline comments for concrete resolutions.
• For Approve with no findings, state that no blocking findings were identified in the reviewed scope.
• For Approve with non-blocking comments, grant approval and call them non-blocking follow-ups.
• Preserve the user's stated rationale when they approve now to avoid needing a second approval after a follow-up.
• Reflect only still-queued findings; do not introduce new concerns or repeat each comment.

Draft Formatting and Completion

Wrap a full Markdown comment payload containing fenced code in a four-backtick outer preview. Never present placeholder code: a suggestion must be syntactically valid and concrete enough to apply, or be prose.

Summarize the outcome: discussed findings, withdrawn/skipped findings, CI limitations or blockers, re-anchoring caused by head changes, and links to comments actually sent. If nothing was published, state explicitly that no further comments were sent.