pr-fix-protocol
Applies reviewer findings to a PR as verified fixes and drives unresolved review threads to zero. Invoked by PR-loop orchestrators (pr-converge, autoconverge, bugteam, qbug, copilot-review) when a reviewer reports findings; not for ad-hoc 'fix this bug' requests outside a PR loop.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 7
- Forks
- 1
01 前言 Front Matter
- name
- pr-fix-protocol
- description
- Applies reviewer findings to a PR as verified fixes and drives unresolved review threads to zero. Invoked by PR-loop orchestrators (pr-converge, autoconverge, bugteam, qbug, copilot-review) when a reviewer reports findings; not for ad-hoc 'fix this bug' requests outside a PR loop.
03 SKILL.md 正文
PR Fix Protocol
Core principle: a finding is addressed only when the fix is pushed, the thread carries a reply, and the thread is resolved — as one unit of work. Anything short of all three leaves a convergence gate stalled.
How callers invoke this
- Skill-capable contexts (a lead session that holds the
Skilltool):Skill({skill: "pr-fix-protocol", args: "--skill <caller> --pr <URL> --worktree <path> [findings payload or 'sweep']"}). - Fallback (a subagent or teammate without the
Skilltool): the caller's spawn prompt says to read~/.claude/skills/pr-fix-protocol/SKILL.mdand apply it with the parameters below.
The caller passes: its identity, the PR scope, the PR worktree path, this round's findings (or sweep for a thread sweep with no fresh findings), and its post-push obligations — which clean-SHA state fields to reset and which reviewers to re-trigger.
Executor choice
- Single-PR loops (no shared
state.json): the lead spawnsAgent(subagent_type: "clean-coder", model: "sonnet")— worker-model routing perskills/orchestrator/SKILL.md; resolver-supplied sonnet-equivalent on third-party hosts — to write the fix. Stop whenAgentis unavailable. A spawned clean-coder starts in its own working directory, so its prompt names the PR worktree path and directs it to edit, stage, and commit there. - Multi-PR orchestration (shared
state.json): a per-PR clean-coder teammate owns edits, replies, and state writes; the orchestrator holds back from inline edits. The teammate obligations — reply before writing state, which state fields to set, idle handoff — live in the calling skill's multi-PR reference.
Run every git command in the PR worktree. git add, git commit, and git push act on the repo of the current working directory, so a cross-repo PR's fix lands in the PR's repo only when the working directory is its worktree.
The fix sequence
Follow the shared 13-step sequence in _shared/pr-loop/fix-protocol.md exactly: read each file:line, capture the pre-fix SHA and contents, write a failing test first where the finding has behavior, apply the fix narrowly, py_compile, run the post-fix self-audit, stage by explicit path, make one commit, fast-forward push, then reply and resolve atomically per thread. Its Constraints section — narrow scope, keep the commit hooks, preserve helpers — binds every executor.
Reply transport: the GitHub MCP add_reply_to_pull_request_comment is primary. For a script-only context or a multi-PR teammate, the fallback is python "$HOME/.claude/skills/pr-converge/scripts/post_fix_reply.py" --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>". Both carry the body shape from _shared/pr-loop/audit-reply-template.md. For a body-only finding with no inline thread, post a top-level review reply that cites the new HEAD SHA.
Thread resolution: call pull_request_review_write(method="resolve_thread", threadId=<PRRT node id>) right after each reply. Harvest the thread node ids (PRRT_…) from get_review_comments at fetch time.
The unresolved-thread sweep (hard gate)
A caller advances a phase, records a clean SHA, or marks a PR ready only when the PR carries zero unresolved review threads.
pull_request_read(method="get_review_comments") → filter threads where is_resolved == false
- The filter is purely
is_resolved == false. Author, anchor commit, andis_outdatedplay no part in the count. is_outdatedis informational, not a skip flag. GitHub marks a thread outdated when its anchor line changes, yet the concern can still apply to current HEAD — the fix may have moved rather than landed. Verify each outdated thread against current HEAD like any other.- Per unresolved thread: verify the concern against current HEAD. The concern holds → fix (this protocol) → reply → resolve. The concern does not hold on current HEAD → reply with a note that explains why → resolve.
- Code changed during the sweep → push and hand control back to the caller's re-entry phase. Only resolutions and no code → re-run the sweep and keep the caller's state.
Post-push obligations
Every push through this protocol:
- Re-resolve
current_head—git rev-parse HEADlocally, and the PRgetcall for API-visible state. - Reset the caller-named clean-SHA fields to null (
bugbot_clean_at,code_review_clean_at,copilot_clean_at— whichever the caller tracks). A new HEAD invalidates every prior clean. - Re-trigger reviewers per the caller's parameter — for Cursor Bugbot the
reviewer-gatesBugbot flow, for Copilot the caller's request step. Audit-family callers (bugteam,qbug) skip re-triggering, since their next loop iteration is the reviewer.
Gotchas
- Reply, then resolve, atomic per thread. Batching every reply ahead of any resolve, or yielding to the orchestrator between the two, leaves threads half-addressed when a run dies mid-loop.
- An unchanged HEAD after step 11 means no commit landed. Exit
stuck — could not address findingsrather than report the findings as fixed. - A resolved thread with no reply reads as dismissed. Reviewers and the humans reading the PR need the one-paragraph explanation the template carries.
Folder map
SKILL.md— this file. The step sequence, reply template, and payload shapes live in_shared/pr-loop/(fix-protocol.md,audit-reply-template.md,gh-payloads.md); the reply fallback script lives inpr-converge/scripts/.
04 同仓库更多 Skills
update
Fast-forwards a local repository's main branch to a remote's main after confirming the repo path and source remote through AskUserQuestion. Use when the user says '/update', 'update main', 'fast-forward main', 'sync main from origin', 'pull latest main into <path>', or 'bring main up to date'.
source-command-sr-loop
Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean
skill-builder
Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers, enforce deterministic scripts. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, skill composition, description trigger catalog, deterministic skill scripts.
session-tidy
Audit, clean, and consolidate session logs in the Obsidian vault. Fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries. Use when session logs feel cluttered or before starting a new project milestone. Triggers on '/session-tidy', 'tidy sessions', 'clean up session logs', 'session audit'.
session-log
Logs a session report as an HTML page, tracks vault context, extracts decisions, and outputs a /rename command. Use for /session-log, 'journal this session', 'log this work', 'session report', 'summarize/log/record this session', 'save session', 'capture session', or 'document what we did'.
run-claude-dev-env
Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.