Swarm PR Feedback Closer

Swarm PR Feedback

Use this skill to close known PR feedback. This is not a fresh broad PR review. Repository-specific bot names and examples below are illustrative; substitute the repo's actual bot and branch-state surfaces when they differ. swarm-pr-review discovers new findings; swarm-pr-feedback ingests existing feedback surfaces, verifies each claim, clusters related problems, fixes confirmed issues, validates the branch, and reports closure status for every item.

Mandatory gate contract. Stage A (structural pre-checks) and Stage B (reviewer + test_engineer) gates and the reviewer + critic closeout gate are MANDATORY for any change made as part of this process. No fix lands, no closure ledger row is marked FIXED, and no PR is published until all three gates pass on the current diff. There is no speed, efficiency, or time exception. See "Mandatory Gates" below for the full protocol.

When the work starts from a prior Profile-A swarm-pr-review run, use the exact user command /swarm pr-feedback <PR_URL> continue from .swarm/pr-review/<run_id>/feedback-handoff.json. The controller validates the terminal review and artifact before atomically creating an unbound feedback gate; the artifact alone is not write authorization. Profiles B/C ingest their task-workspace handoff directly before triage. Carry forward the original review finding IDs, classifications, reviewer/critic provenance, and any operational blockers instead of renumbering them as new discoveries.

Feedback closure is not the end of the PR lifecycle: when PR monitoring is enabled (pr_monitor.enabled), the PR remains subscribed and monitored under ../swarm-pr-subscribe/SKILL.md until it is merged or closed. Events that arrive after closure (a new bot round, a CI change, fresh review activity) are triaged through that skill and route back into this discipline when they need fixes.

Multi-Round Bot Reviews (Iterative Pattern)

When the repo uses an auto-review bot that posts a new review comment after every push to the PR branch, identify that bot from the repository contract and apply this pattern (for example hermes-pr-review in this repo). Expect N rounds of review for N pushes, and budget for it.

Round N+1 deltas vs Round N:

• Fresh FB-### ledger IDs for new findings (do not reuse IDs from earlier rounds)
• Findings from prior rounds that remain unfixed will reappear with the same evidence
• Findings you marked DISPROVED with new evidence may reappear if the bot disagrees
• New findings may be introduced that the prior round did not see (the bot's read scope is the new commit, not the full diff history)

Operating principles for multi-round triage:

1. Continue the ledger, do not start over. Append to the same FB-### counter across rounds. Track each finding's state per round (open, fixed, disproved, awaiting-decision, repeated).
2. Carry forward unresolved items. Findings you marked PARTIAL or NEEDS_USER_DECISION in round N will still be open in round N+1. The closure ledger should show their evolution (e.g., "PARTIAL round 1 → CONFIRMED round 2 after evidence collected").
3. Apply the 3-strikes evidence-escalation rule. When the same finding is raised 3+ times across rounds, re-run source verification with a fresh reviewer context and surface the disagreement explicitly. Add a defense-in-depth change only when that fresh verification proves the change is correct, preserves the real invariant, and adds meaningful protection. Repetition, time, token cost, and reviewer persistence are never substitutes for evidence. Document any parent-vs-inner relationship inline so future readers see the rationale. Do not add the repeated suggestion: If it would add incorrect or misleading code about existing guards — e.g., an outer guard that already exists at an inner scope and whose addition would imply the inner guard is absent, a type narrowing that masks a real error class, or a check whose presence asserts a false invariant — do not add the change. A wrong fix embedded in the code is harder to remove than a repeated rebuttal in a comment thread. When the repeated finding is misleading about existing guards, apply item 6's "surface to user" path instead of 3-strikes; otherwise the 3-strikes rule applies.
4. Verify bot fix-direction suggestions against actual file structure. Bots read files linearly and can miss parent-block guards. For any "add an X check" suggestion, read the surrounding function/block to confirm the check is genuinely missing or already exists at a higher scope.
5. Each round produces its own closure ledger as a PR comment. Prefix with "Round N" so the bot and reviewers can see progression. Maintain a running summary table at the end of each comment showing totals across rounds (confirmed+fixed / disproved / partial / awaiting-decision).
6. Stop the cycle deliberately. If a finding is disproved with code evidence 3+ times and the bot keeps re-raising it, leave the comment, post the closure ledger with the cumulative evidence, and surface the disagreement to the user rather than continuing to push fixes. The user can resolve persistent reviewer-AI disagreement.

Why this matters: Without the multi-round pattern, each round looks like "start over, re-triage everything." With it, the rounds become incremental: each round's work is bounded by new findings + carried-forward items only. This matches how the bot actually behaves and avoids wasted cycles.

Bot and Security Claim Verification

Before trusting automated review findings (SAST bots, security scanners, AI reviewers), apply the verification protocol in references/bot-claim-verification.md. Key principle: every bot claim is unverified until you reproduce the exact finding against the current HEAD with the exact tool and rule it names.

Operating Stance

Treat every review comment, CI failure, bot summary, PR body claim, and pasted note as a claim until source evidence proves it. Do not silently drop, defer, or mark items out of scope. Ask the user only for product or scope decisions that cannot be proven from the PR, repo, or explicit instructions.

Do not run a fresh broad PR review while addressing existing feedback. Inspect adjacent code only as needed to verify reachability, dependencies, shared root causes, regression risk, or sibling changes required by a confirmed item.

GitHub review-thread resolution is user-controlled. Do not resolve or mark review threads resolved unless the user explicitly instructs you to do so.

Do not act on review-discovered findings from a prior swarm-pr-review run unless the user has explicitly approved the transition into swarm-pr-feedback. The handoff artifact is triage input, not standing authorization to change code.

Runtime Capability Profiles

This skill runs on any agent harness. Detect the active profile from the actual tool list before triage — the same three profiles defined in ../swarm-pr-review/SKILL.md (Runtime Capability Profiles):

• Profile A — mechanical PR-feedback controller. The plugin's tools are present in this session: dispatch_lanes_async, collect_lane_results, retrieve_lane_output, prepare_pr_feedback_scope, run_pr_feedback_stage_a, complete_pr_workflow. The controller's fail-closed accounting (immutable inventory, ordered gate lanes, content digests, arming, bound push) is authoritative; bypassing it — direct subagent calls, blocking dispatch, prose verdicts — is BLOCKED while it is active.
• Profile B — native parallel subagents, no controller. Run the same intake → verify → fix → gate → publish discipline using your harness's subagent tool for verification lanes and gate roles; you maintain the ledger, the ownership partition, and the digest accounting yourself in session/task workspace files (never under .swarm/, which belongs to the plugin runtime).
• Profile C — single context, no subagents. Same discipline as strictly separated sequential passes that re-derive rather than restate earlier reasoning, plus explicit disclosure in the closure ledger that gate independence was procedural.

Controller-tool absence is NOT a blocker; Profiles B and C are first-class execution paths. BLOCKED is reserved for bypassing an active controller and for verification or coverage gaps that stay unclosable after bounded retries.

Pre-flight: Check Out the PR Branch Locally

Before verifying any claim or making any fix, ensure the PR branch is the working tree:

• If head_ref is a remote branch that is not checked out locally, fetch it (git fetch origin <head_ref>).
• Check for parallel work first. Before checkout, use the repository or runtime's parallel-work check. When the bundled parallel-work-check skill exists, it is one conditional implementation to detect concurrent pushes from other agents (for example the repo's auto-review bot following up, a maintainer pushing fixes, or parallel swarm work). If remote has new commits: read git log local..remote, evaluate whether the parallel work supersedes your planned fixes, and prefer the parallel work if it's more comprehensive (more tests, better edge coverage, clearer error handling). Abort your rebase, take the remote state, then add minor improvements on top.
• Verify the working tree is clean first (git status --porcelain). If any tracked or untracked changes exist, call prepare_pr_workflow_checkout before binding (Profile A). Omit paths to auto-discover and atomically preserve every dirty path, including untracked files; pass explicit paths only for an exact bounded tracked-file set. It creates an auditable stash receipt containing the original branch/HEAD and a structured operation: "restore" recovery instruction. Do not issue git stash through shell. Without the controller, surface dirty state to the user or abort the checkout — do not blind-stash.
• Treat recovery-required and indeterminate controller results as terminal for the current attempt: report the typed required_action, abort/clear any already-active gate, and stop. Only stashable permits one preparation call; retry only when the controller explicitly returns retryable: true.
• Check out the head branch locally before dispatching feedback lanes. Feedback verification reads the working-tree filesystem (Read/Glob/Grep), and fixes must land on the PR branch — without a checkout you would verify and patch the base branch's code instead. Record the exact merge_base...head_ref range for diff-scoped inspection.
• Pass the exact merge_base...head_ref commit range in every read-only verification or explorer/advisory-lane delegation so lane agents can inspect specific revisions with git show when needed.
• If no PR reference was provided (a pasted-feedback session on the current branch), confirm the current branch is the intended PR branch before editing.
• A detached checkout at the authoritative full PR head is a valid pre-bind intake state. On the first Profile-A bind, the controller attaches it only when Git reports exactly one safe candidate: an existing local branch at that SHA whose upstream is an exact remote ref at the same SHA, or one exact remote-tracking ref. It never guesses a remote/name boundary. Zero candidates, multiple candidates, a linked-worktree-owned local branch, or an existing mismatched upstream fails closed without publishing the bind. Retry is idempotent if switching succeeded but state persistence failed.
• The existing constrained tracked-branch and safe gh pr checkout pre-bind forms remain supported on every profile after proving the exact SHA and a unique intended remote ref. Never use force, submodule-recursive, or detached gh pr checkout variants.
• Immediately after the first bind and before feedback verification dispatch, prove that git rev-parse HEAD equals the authoritative full pr_head_sha, git status --porcelain is empty, and the current branch tracks the intended PR head remote/branch. A detached exact-head checkout is intake-only; the bind must attach it before feedback dispatch or publication.

When a verification lane result includes output_ref, treat output as a preview and call retrieve_lane_output before using it to classify, resolve, disprove, or group feedback items. If the result is output_degraded, transcript_incomplete, or truncated without a usable ref, keep the affected ledger items as NEEDS_MORE_EVIDENCE or re-dispatch a narrower read-only lane. (Profile A. On Profiles B/C, read each verification subagent's or pass's full report directly — a truncated or summary-only report is a preview, not verification evidence, and keeps its items open the same way.)

Pre-flight: Dirty Worktree Handling

Before staging any files for the PR commit, check the working tree state:

The problem: git add -A stages every uncommitted change in the working tree, including pre-existing changes from other branches or prior work.

The check: Run git status --porcelain first. If output is non-empty, identify which files are PR-related vs pre-existing uncommitted changes.

The rule: Stage files explicitly by path when the working tree contains files unrelated to the PR. For example:

git add src/foo.ts tests/foo.test.ts

Never use git add -A when the working tree has pre-existing changes from other branches or prior work sessions.

Batch Collection (mandatory before any fix)

When the runtime provides a CI-failure-batching workflow, load it before proceeding. The bundled ci-failure-batching skill is one conditional implementation; otherwise apply the host-neutral complete-ledger protocol below.

For the detailed 6-step batch collection protocol, read file:.swarm/bundled-skills/ci-failure-batching/SKILL.md. The steps below are a summary:

1. gh pr checks <number> --json name,bucket,state,link to collect all check results
2. Filter to bucket == "fail" or bucket == "cancel"
3. gh run view <id> --log-failed for each failing run
4. Group failures by root cause before fixing

Rule: The complete failure ledger must be collected before any modification is proposed. Verifying the ledger is complete is a prerequisite for the Fix Planning step.

Pre-flight: Scope Discipline

When the plugin's mechanical controller is available, every coder Task must be preceded by prepare_pr_feedback_scope({ task_id, files }). The controller is available only after the immutable feedback-verification lanes have settled and binds the exact file set to the current feedback revision, parent session, and next matching Task call. The coder prompt must use the same numeric task_id, contain matching FILE: directives, and include a literal ACCEPTANCE: line. Once a Task consumes that scope, its task_id is immutable for the current feedback revision. Any retry must prepare and dispatch a fresh nested numeric task identity (for example 1.1.1), never re-declare the consumed ID.

Do not create a synthetic save_plan merely to authorize feedback work, and do not use declare_scope; those tools belong to the normal implementation-plan lifecycle. There is no one-file or single-function carve-out from the dedicated PR-feedback scope controller.

In runtimes without this controller, use the native scope mechanism. If none exists, put exact allowed files and non-goals in the delegation and verify the resulting diff mechanically. Never bypass an available scope controller merely to reduce ceremony.

Intake Surfaces

Build a complete feedback ledger before editing. Include every available source:

• validated findings and operational blockers handed off from swarm-pr-review,
• pasted user or reviewer feedback,
• GitHub review threads, inline review comments, and review summaries,
• PR issue comments and requested-changes reviews,
• CI/check failures, check annotations, and relevant logs,
• mergeability, conflicts, base drift, and stale PR branch state,
• local validation failures,
• PR body checkboxes, test-plan claims, linked issues, and acceptance criteria,
• commit history and bot/app commits on the PR branch.

If a source is unavailable, retry with alternative access paths. If unavailable after retry, the source is a coverage gap that must be reported to the user — do not silently "record that limitation" and proceed as if the source doesn't matter.

Async advisory verification lanes

After the complete feedback ledger exists and before editing, run independent read-only verification lanes. Under Profile A, use dispatch_lanes_async with mode: "swarm-pr-feedback:verification", the complete immutable feedback_inventory ID list, the exact current pr_head_sha, and each lane's exact feedback_item_ids ownership list for independent read-only verification lanes: comment classification, CI/log root-cause inspection, test impact mapping, release/docs claim checks, and stale-branch/conflict analysis. Partition the ledger so each FB-### item is owned by exactly one verification lane and the union of lanes covers the entire ledger — no feedback item may be left unassigned to a lane; state each lane's owned IDs both structurally and in its prompt. The runtime rejects missing, duplicate, overlapping, or unknown item ownership and blocks mutation until the verification batch settles. Scale the lane count to the ledger size: a 1–3 item round may use a single combined lane, while a large multi-round intake may warrant one lane per category above. Cap each dispatch_lanes_async batch at 8 lanes (MAX_LANES); if the ledger needs more than 8 verification lanes, dispatch in sequential batches and settle each batch's COVERAGE GATE before the next — do not over-spawn lanes for a trivial round. Record each returned batch_id, then continue only ledger-safe architect work: normalize feedback IDs, gather deterministic PR metadata, prepare reproduction commands, and plan likely fix groups. Do not edit, close items, or mark feedback resolved from running lanes.

Every verification lane must end with one parseable row for each owned item:

[FEEDBACK-VERIFIED] | FB-### | CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING/NEEDS_MORE_EVIDENCE/NEEDS_USER_DECISION | evidence

Non-empty prose without this marker contract is not a settled verification artifact and cannot unlock mutation.

Before the Verification step can mark any item CONFIRMED, PARTIAL, DISPROVED, PRE_EXISTING, NEEDS_MORE_EVIDENCE, or NEEDS_USER_DECISION, every open verification batch must be fully settled. Poll with collect_lane_results (wait omitted or false) to process settled lanes incrementally — clustering confirmed items and pre-reading files for settled findings while ledger-safe work remains — then issue a final collect_lane_results with wait: true per batch once independent work is exhausted, to confirm every lane is settled. Missing, stale, cancelled, or failed lanes are coverage gaps that must be closed before marking any item CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING. Apply the COVERAGE GATE: retry failed lanes (max 2) as another swarm-pr-feedback:verification async batch with the same immutable inventory, exact pr_head_sha, agent type, prompt, scope, and isolation, or stop and surface the lane failure to the user as BLOCKED. Under Profile A, blocking and direct-Task fallbacks are rejected because they cannot satisfy the durable ownership and head-provenance gate. Do not proceed with "blocking verification and record that async advisory lanes were unavailable" — record-and-continue is not coverage closure.

Under Profile B, partition the same immutable inventory across fresh read-only verification subagents — every FB-### item owned by exactly one lane and the union of lanes covering the entire ledger — with each prompt stating its owned IDs and the exact pr_head_sha, and each lane returning one [FEEDBACK-VERIFIED] row per owned item. Under Profile C, verify the ledger in sequential category passes with the same one-row-per-item contract. On every profile, no item may be classified until its verification lane or pass has settled, and unclosable verification gaps are surfaced as BLOCKED.

CI matrix cascade check (do this before fixing)

When the PR's unit job is a matrix across multiple OSes and downstream jobs (integration, smoke) have needs: unit, an OS leg failure blocks the entire pipeline. Before triaging, check:

1. Are integration or smoke jobs in skipped or cancelled state rather than failed? That signals a unit matrix cascade — the unit job failed on one OS leg, blocking the downstream jobs from running on the current HEAD.
2. If a unit OS leg is the blocker, classify the failure:
   • Code issue — the test itself fails. Reproduce locally; if the test passes locally, the runner is the problem.
   • Runner performance — the test step exceeds the configured timeout. Run all files in the step locally with per-file timing; if cumulative local runtime is <10 min and the runner can't complete in 60+ min, the issue is runner performance. Bump the CI timeout as a stopgap and file a follow-up issue for parallelization. Do not loop bumping the timeout past 90 min without filing the follow-up.
3. Surface cascade failures to the user explicitly. The downstream jobs' results don't exist; the code's coverage of the current HEAD cannot be confirmed by CI alone.

PR body claim verification

The .swarm/evidence/ paths below apply only when the reviewed repository uses this plugin's council evidence contract. For any other repository, locate the authoritative CI attestation, code-host review record, or repository-declared evidence store; the universal rule is that an approval claim needs a real, retrievable provenance artifact.

PR body text like "PHASE 2 council APPROVED (5/5, round 2)" or "Final council APPROVED" must be backed by an evidence file under .swarm/evidence/ — phase councils write .swarm/evidence/{phaseNumber}/phase-council.json; the final council writes the flat .swarm/evidence/final-council.json. Bot-generated PR bodies commonly auto-fill these claims without real review. Before accepting such a claim as part of triage:

1. Check whether the corresponding evidence file exists with verdict:APPROVED.
2. If the claim is unsupported, mark the closure ledger item as NEEDS_MORE_EVIDENCE rather than CONFIRMED. Do not silently drop the claim — it indicates the PR body was generated without a real review.

Feedback Ledger

Normalize each item before triage:

FB-001 | source | author/tool | status: UNTRIAGED | location | claim | raw link/quote | depends_on

Rules:

• Preserve prior F-###, CI-###, CONFLICT-###, STALE-###, and similar IDs from a review handoff when they already exist. Only mint fresh FB-### IDs for new feedback discovered after the handoff.
• Preserve reviewer/critic provenance from the handoff artifact so the closure ledger can show which items were review-validated before fix work began.
• Preserve exact reviewer wording or log summary when practical.
• Split compound comments into separate ledger items only when they require different evidence or fixes.
• Keep duplicate symptoms linked to one root cause rather than deleting them.
• Include conflicts, stale branch state, obsolete older-head CI, generated-output (dist/) drift, and other CI failures as first-class ledger items.
• Use explicit IDs for non-review feedback when useful, for example CONFLICT-001 for merge/base drift and CI-001 for check failures, so PR bodies can show exactly how operational blockers were closed.

Mandatory: integrate all PR comments with feedback or findings before branch validation (Stage A)

Before branch validation (Stage A) can begin, every PR comment that contains feedback or findings MUST be integrated into the total feedback ledger as a FB-### item. This is a hard requirement, not a best-effort step.

What counts as "feedback or findings":

• A reviewer request for a code change ("please rename this", "add a test for X", "this should call _internals.foo")
• A reviewer claim about correctness, security, or style ("this is incorrect", "X will leak")
• A bot reviewer's findings table entries
• A CI failure with a specific file:line root cause
• A reviewer question that implies a code change is needed ("why is this static?")
• PR review summaries or aggregate comments

What does NOT count (and is therefore not required to be a ledger item):

• Pure acknowledgements ("LGTM", "looks good")
• PR-level metadata changes (title, label, milestone)
• Force-push acknowledgements

Rules:

• No finding may be addressed outside the ledger. If you fix something a reviewer mentioned, the corresponding FB-### item MUST be in the ledger before the fix. If you skip the fix, the FB-### item MUST be in the ledger with a DISPROVED, PRE_EXISTING, NEEDS_MORE_EVIDENCE, or NEEDS_USER_DECISION status before branch validation (Stage A) can begin.
• Status semantics for unaddressed items:
  • CONFIRMED and PARTIAL items must be addressed (fixed or disproved) before branch validation (Stage A) can begin. A CONFIRMED item that is left unaddressed is a regression against the review.
  • DISPROVED, PRE_EXISTING, NEEDS_MORE_EVIDENCE, and NEEDS_USER_DECISION items may remain open at branch-validation (Stage A) time, but each must be explicitly justified in the closure ledger.
• The closure ledger at the end of the run must account for every FB-### item with a final status (fixed / disproved / pre-existing / needs user decision / needs more evidence).
• Comments from the latest bot round take precedence over earlier rounds for the same finding; the earlier-round FB-### item is updated with the new evidence rather than a new item being created.
• Multi-round pattern continues to apply (see "Multi-Round Bot Reviews" section). A new bot round adds new FB-### items for findings that weren't in the prior round; the prior round's items are carried forward and updated with the new evidence.

Rationale: silently addressing a review comment without a corresponding ledger item means the closure summary at the end of the run cannot demonstrate that every review comment was considered. The closure summary is the only artifact the user/maintainer reads to confirm the PR is ready to merge. Missing items in the ledger = missing items in the closure = a PR that ships with unreviewed feedback.

Verification

Classify every ledger item before fixing:

Verification checklist:

• Read the referenced file and surrounding code.
• Check caller context, reachability, feature flags, schema validation, guards, state-machine rules, and permission boundaries.
• Determine whether the issue is PR-introduced, pre-existing, or unresolved.
• Check related tests and whether a failing/proposed test would prove the item.
• Check whether multiple feedback items share one root cause.

DI seam migration validation

When the repository uses _internals seam / mock.module() patterns, apply the validation protocol in references/operational-gotchas.md.

Fix Planning

Cluster ledger items by root cause before coding. Fix in this order unless a user instruction or dependency requires otherwise:

1. Merge conflicts, stale branch state, and base drift.
2. Deterministic CI, build, typecheck, formatting, and test failures.
3. Confirmed correctness, security, data-loss, persistence, git/write-safety, and permission issues.
4. Test gaps needed to prove confirmed fixes.
5. Docs, release notes, PR body, and migration guidance.
6. Reviewer communication and closure summaries.

For each cluster, record:

ROOT-001 | ledger items: FB-001, FB-004 | files | fix approach | tests | docs | risk

Do not make scope decisions yourself. If the right fix depends on product intent or compatibility policy, mark the item NEEDS_USER_DECISION and ask.

Implementation Rules

• Patch only confirmed or partial items, plus required tests/docs.
• Do not implement speculative cleanup while feedback remains unclosed.
• Never ship unwired code. Any new command, tool, skill, config, docs surface, or generated artifact must be fully registered and validated.
• Never defer work or declare it out of scope without explicit user instruction.
• Keep invalid or disproved findings in the closure ledger with the evidence.
• For CI failures, verify the failing job belongs to the current PR head before treating it as current evidence.
• For generated output or dist failures, inspect the failing log before rebuilding and commit regenerated files only when the PR touches the source surface.
• When main has a merge queue enabled, do not rebase or force-push a PR only because main advanced. Once required checks and review are green, queue the PR and let the merge queue perform final current-base validation. Still resolve real merge conflicts and SHA-dependent review threads before queuing.

Conditional runtime/host gotchas

For portability gotchas (plan identity, stale gate evidence, PowerShell comment posting, same-file batching), read references/operational-gotchas.md.