AGENT SKILL

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 Skill tool): Skill({skill: "pr-fix-protocol", args: "--skill <caller> --pr <URL> --worktree <path> [findings payload or 'sweep']"}).
  • Fallback (a subagent or teammate without the Skill tool): the caller's spawn prompt says to read ~/.claude/skills/pr-fix-protocol/SKILL.md and 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 spawns Agent(subagent_type: "clean-coder", model: "sonnet") — worker-model routing per skills/orchestrator/SKILL.md; resolver-supplied sonnet-equivalent on third-party hosts — to write the fix. Stop when Agent is 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, and is_outdated play no part in the count.
  • is_outdated is 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:

  1. Re-resolve current_head — git rev-parse HEAD locally, and the PR get call for API-visible state.
  2. 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.
  3. Re-trigger reviewers per the caller's parameter — for Cursor Bugbot the reviewer-gates Bugbot 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 findings rather 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 in pr-converge/scripts/.

04 同仓库更多 Skills

jl-cmd-projects
jl-cmd-projects/claude-dev-env

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'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

source-command-sr-loop

Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

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.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

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'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

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'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

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.

★ 7