monitor-pr
Continuously watch a GitHub PR (usually one Claude just opened) for CI failures and new review comments, and drive fixes as they arrive. Use when the user says "monitor this PR", "watch PR
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- monitor-pr
- description
- Continuously watch a GitHub PR (usually one Claude just opened) for CI failures and new review comments, and drive fixes as they arrive. Use when the user says "monitor this PR", "watch PR
- allowed-tools
- Bash Read Write Edit Skill ScheduleWakeup TaskCreate TaskUpdate
- disable-model-invocation
- true
02 资源文件 1
- 脚本scripts/poll-pr.sh4.8 KB
03 SKILL.md 正文
Monitor PR
Shepherd a Claude-authored PR to green without a human babysitting the tab. On a
repeating interval, poll the PR for CI failures and new review comments;
whatever is actionable becomes a ledger finding, is fixed and committed by
/review:fix, is pushed, and — for the bot's own review threads — gets resolved.
Suggestions and human comments are surfaced for a decision, never silently acted on.
This skill edits no source file and commits nothing. It polls, triages,
pushes, and talks to GitHub. Editing is /review:fix's job.
Core principles
- Baseline, then diff. Snapshot the PR once at start. On every later tick, act only on what is new or still-open versus that baseline — never re-litigate a comment already handled or a check already green. (Learned the hard way: without a baseline the monitor churns on stale findings.)
- One monitor per PR. Before starting, check for an existing tracker for this PR. If one is active, resume it — do not spin up a second loop. Two monitors on one PR means double subagents, double commits, confusion.
- The ledger is the source of truth; the tracker is a mirror. Finding state
lives in
~/.claude/review-findings/<owner>__<repo>/pr-<n>.json, outside the repository and shared with/review:fix. The tracker is the human-readable view of it, carrying the same ledger IDs. When they disagree, the ledger is right. - Fix what's yours; ask about the rest. CI failures and the bot's own unresolved review threads are auto-fixed. Human review comments and nit/suggestion-level items are logged and reported for the user to decide — pause and ask before acting.
- Delegate the fixing. Parallelism, partitioning, and the agent contract belong
to
/review:fix, which owns one lock per ledger and one commit per finding. This skill groups nothing, dispatches nothing, and edits nothing. Append the finding, call the skill, read the result back. - Respect the permission deny-list in
shared/fix-contract.md, which is the single copy both skills work from. Nevergh pr merge, never force-push, nevergit reset --hard, never touch the default branch. Fixes are pushed to the PR branch. Merging stays with the user; surface the command, don't run it. The one line that differs between the two callers:/review:fixpushes when invoked directly, but not here — the push is this skill's job. Phase 2 passes--no-pushfor exactly that reason, and nothing it committed reaches GitHub until Phase 3 runs. Dropping that flag would hand the push to the fixer mid-tick, before this skill has reconciled the tracker.
Inputs
/monitor-pr <pr-number> [--repo owner/name] [--auto | --critical-only]
<pr-number>— required.--repodefaults to current repo (gh repo view).- Default mode: auto-fix CI failures + unresolved bot review threads; gate human comments and suggestions (log + report + ask).
--auto— also act on human comments and suggestions without pausing.--critical-only— act only on CI failures and blocking bot threads; ignore nits.
Work happens in the PR's worktree/checkout. If the session isn't already there, check
out the PR branch first (gh pr checkout <n>); prefer running under a worktree from
start-session.
The ledger and the tracker
The ledger — where state lives
The same file /review:review writes and /review:fix consumes. Resolve its path
with the plugin script rather than composing it by hand:
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
if [ ! -f "$PLUGIN_ROOT/scripts/findings_ledger.py" ]; then
PLUGIN_ROOT="$(cd "${CLAUDE_SKILL_DIR:-.}/../.." 2>/dev/null && pwd)"
fi
LEDGER_PY="$PLUGIN_ROOT/scripts/findings_ledger.py"
POLL="$PLUGIN_ROOT/skills/monitor-pr/scripts/poll-pr.sh"
LEDGER=$(python3 "$LEDGER_PY" path --repo "$REPO" --pr "$PR_NUMBER")
RUN_ID="monitor-$PR_NUMBER-$(date -u +%Y%m%dT%H%M%SZ)"
Both paths are absolute on purpose. The working directory is the reviewed
repository, not this plugin, so a bare scripts/poll-pr.sh finds nothing — or
worse, finds a same-named script in the repo under review.
LEDGER_PY holds the path only, and python3 stays at the call site. Folding the
interpreter into the variable works in bash and silently breaks in zsh, which does
not word-split an unquoted expansion.
The ledger holds each finding's status, its external_ref (the check or thread it came
from), and its resolved_by_sha once fixed. It sits outside the repository, so it
survives compaction, git clean, and a worktree switch — and it is what lets the
monitor and the fixer agree on what is already done.
The tracker — the human-readable mirror
Path: .claude/pr-monitor/pr-<n>.md (create the dir if needed). It exists so a
person can read the monitor's state at a glance. It is not the store: every row
carries the ledger ID it mirrors, and a disagreement is settled by re-reading the
ledger, never by editing the tracker to match a memory.
# PR #<n> monitor — <owner/name>
branch: <head-branch> · mode: <default|auto|critical-only>
ledger: ~/.claude/review-findings/<owner>__<repo>/pr-<n>.json
baseline @ <first-poll>: checks=<pass/fail/pending> · threads bot=<n> human=<n> · reviewDecision=<...>
last poll: <ts> · last summary: <one line>
## Open
- [ ] F003 · ci · critical · check="build (rust)" · with review:fix
- [ ] F004 · review-bot · critical · thread=PRRT_x · src.rs:88 · with review:fix
- [ ] F005 · review-human · needs-decision · thread=PRRT_y · api.ts:12 · REPORTED, awaiting user
- [ ] F006 · review-bot · deferred by fix · decision: outbox table, CDC, or accept the window?
## Done
- [x] F001 · ci · check="lint" · <sha> · pushed @ <ts>
- [x] F002 · review-bot · thread=PRRT_z · <sha> · pushed, thread resolved @ <ts>
Rows carry no owner=agent:… — this skill owns no agents. A finding in flight is
"with review:fix", and its authoritative status is the ledger's.
Refresh it from python3 "$LEDGER_PY" show after each phase. Delete it when Open is empty
and CI is green — that is the signal the monitor's job is complete. The ledger
stays: it is the record of what was fixed, what was deferred, and why.
Triage matrix
Signal (from poll-pr.sh) |
Default | --auto |
--critical-only |
|---|---|---|---|
CI check failing |
fix | fix | fix |
| Bot thread, unresolved, blocking/critical | fix + resolve | fix + resolve | fix + resolve |
| Bot thread, nit/suggestion | report + ask | fix + resolve | ignore |
| Human review thread / requested change | report + ask | fix | report + ask |
| Human issue comment | report + ask | fix | report + ask |
pending checks |
wait (tighten interval) | wait | wait |
| all green, no open threads | converge → cleanup | converge | converge |
fix here means append to the ledger and let /review:fix do it — this skill
never edits. report + ask means the finding is not appended at all; it stays out
of the ledger until the user says otherwise. ignore appends nothing and asks
nothing.
"Blocking/critical" vs "nit": judge from the comment body and any reviewDecision: CHANGES_REQUESTED. When unsure, treat a bot thread as fixable and a human thread as
needs-decision. Every fix in this table implies the Phase 3 acknowledgement — once
the fix is pushed, resolve the corresponding thread, or reply @author if it isn't
resolvable. This applies to human comments too, whenever their fix actually ships.
Workflow
Phase 0 — Start / resume (once)
- If
.claude/pr-monitor/pr-<n>.mdexists → resume: read it, then reconcile against the ledger (python3 "$LEDGER_PY" show --ledger "$LEDGER" --json), which is authoritative. Skip re-baselining. Otherwise run"$POLL" <n> [--repo …], write the baseline block, and append every currently-failing check and unresolved actionable thread to the ledger as in Phase 2. - Check whether a ledger exists.
/review:reviewwrites it; a PR that was never reviewed has none, and Phase 2 will create one with--create. A created ledger has an emptycontextblock — notest_setup.test_command, so/review:fixhas no local signal and commits unverified, leaning on CI. That is a real limitation, not a detail: say it in the announcement, and suggest/review:review <pr-url>first when the PR has not been reviewed. - Announce the monitor is live and the cadence, then begin the loop.
Phase 1 — Poll (each tick)
Run the read-only snapshot:
"$POLL" <n> [--repo owner/name] # JSON: checks, threads{bot,human}, reviewDecision, mergeStateStatus
Diff against the ledger. New failing checks and newly-unresolved threads become
findings to append in Phase 2; checks that went green and threads now
resolved/outdated move to Done in the tracker. Merged/closed PR → stop and clean up.
A finding already in the ledger as deferred is not new, however the poll looks
— /review:fix decided a human has to answer it. Leave it where it is.
Phase 2 — Hand the findings to /review:fix
This skill writes no file in the repository and makes no commit. It converts what the poll found into ledger entries and calls the fixer.
1. Append each new actionable finding, with the external_ref that is its
return path to GitHub. Dedupe is the ledger's job — an unresolved thread re-polled
every tick appends once.
A failing CI check, piped from the classifier
(scripts/review_formatter.py's classify_ci_failure):
printf '%s' "$CI_JSON" | python3 "$LEDGER_PY" append --ledger "$LEDGER" --source ci \
--create --pr-url "$PR_URL"
An unresolved review thread, from the threads array poll-pr.sh already returns:
printf '%s' "$THREADS_JSON" | python3 "$LEDGER_PY" append --ledger "$LEDGER" \
--source review-thread --create --pr-url "$PR_URL"
--create is a no-op once the ledger exists, so both commands are safe every tick.
Gated findings are never appended. A human comment or a nit in default mode
stays out of the ledger entirely — appending it would hand /review:fix work the
user has not approved. Mark it needs-decision in the tracker, report it, and ask.
Only after the user agrees does it get appended.
Transient CI failures — a timeout, a network blip — classify as info and the
normalizer drops them. Nothing to fix; the next poll re-runs them.
2. Call the fixer.
Skill review:fix <n> --no-push
It takes the ledger lock, routes every open finding to a strategy, applies it,
makes one commit per finding, and runs the suite once per partition — iterating
until the branch is green before it returns. --no-push is required, not
decorative: invoked without it the fixer pushes its own green branch and
acknowledges its own threads, which would double up with Phase 3.
Do not pass a finding list. Selection is status == "open", which is exactly the
set just appended plus anything an earlier tick could not finish.
3. Read the result back.
python3 "$LEDGER_PY" show --ledger "$LEDGER" --status committed,deferred --json
Each committed finding carries resolved_by_sha; each deferred one carries
deferral.decision_needed. Mirror both into the tracker. A deferred finding is a
question for the user, not a retry — re-appending it next tick would loop forever.
If /review:fix pauses on a finding it could not get to green, it surfaces that
as a question. Pass it through to the user unchanged; do not re-run the fixer over
it and do not push a partial result past it.
Phase 3 — Push, then close the loop
/review:fix left its commits on the local head branch. Nothing has reached GitHub
yet, so CI has not re-run and no thread can honestly be resolved.
-
Push the head branch.
git -C "$WORKTREE" push origin HEADNever
--force, never--force-with-lease, never a refspec naming the default branch. A rejected push means the remote moved: pull with rebase off, inspect, and report — do not resolve any thread, because the fix is not on the PR.Push once per tick, after the fixer returns, not once per commit. Each push triggers CI.
-
Mark every finding the push carried
pushedin the tracker, against its sha. -
Always acknowledge the comment that prompted the work — non-negotiable once the fix is on the PR branch, for bot and human comments alike. The handle is in the finding's
external_ref(thread_id,comment_id,author), which is why it is recorded at append time and survives the round trip through the fixer.Skip any finding that already carries an
acknowledgedentry for that thread./review:fixcan also reply and resolve — for work that was already pushed when it ran, or when a user invoked it directly with--ack-only— and the ledger is what keeps one reviewer from being answered twice. Record each acknowledgement the same way:python3 "$LEDGER_PY" ack --ledger "$LEDGER" --id <ID> --thread <thread_id> \ --action reply+resolve --run "$RUN_ID"A deferred finding gets a reply stating the decision it needs, and the thread stays open. Resolving it would hide the one finding that most needs a human.
- Inline / resolvable review thread → resolve it:
gh api graphql -f query='mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread{ isResolved } } }' -F id="<threadId>" - Not inline / not resolvable (a PR-level issue comment, or any comment with no
resolve handle) → reply with a new comment that @-mentions the original author
and points at the fix:
To reply inside an existing review thread instead of at PR level:gh pr comment <n> --body "@<author> addressed in <sha> — <one-line of what changed>."gh api repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies -f body="@<author> addressed in <sha> — …"
- Inline / resolvable review thread → resolve it:
-
Let CI re-run; the next poll confirms green or surfaces a follow-up failure.
Phase 4 — Converge and clean up
When Open is empty and CI is green and no unresolved actionable threads
remain:
-
Post/keep a short summary: what was fixed, what was pushed, what still needs the user (gated items, deferrals from
/review:fix, merge). -
Delete the tracker
.claude/pr-monitor/pr-<n>.md. Keep the ledger — it records what was fixed and what was deferred, and a reopened PR resumes from it. -
Release the fixer's lock if a killed run left one:
python3 "$LEDGER_PY" unlock --ledger "$LEDGER" -
Stop scheduling further ticks. If
mergeStateStatusisBLOCKEDonly on approval, say so — do not attempt the merge.
Cadence — drive with /loop
Built to run as a loop. Drive it with the /loop skill: each firing
re-enters and runs one Phase 1→3 tick. Under the hood that uses ScheduleWakeup for
dynamic pacing — if you aren't launched via /loop, self-schedule the next tick with
ScheduleWakeup.
Pick the interval by what you're waiting on (align to the prompt-cache window):
- CI running / fixes in flight → ~240s (checks resolve in minutes; stays cache-warm).
- Idle, awaiting human review → ~1200–1800s (nothing changes minute-to-minute).
- Stop the loop entirely at Phase 4, or if the PR is merged/closed.
Always pass the same /monitor-pr <n> prompt back so the next firing repeats the tick.
Gotchas
- No
Agentinallowed-tools, deliberately. Dispatch belongs to/review:fix, which pinssubagent_typeandmodelper strategy. An agent launched from here would inherit the session model and commit from a second.git/index. - Deferred tools.
ScheduleWakeupis native. If you track in-flight work withTaskCreate/TaskUpdate, the ledger stays the source of truth (it survives compaction; task state may not). poll-pr.shmutates nothing. It only reads. Appending, pushing, and thread resolution are your job, per the matrix; editing and committing are not.- Bot detection. The script flags authors containing
claude-code-actionor ending[bot]as bots. If this repo's Claude reviewer uses a different login, pass it viaCLAUDE_BOT=<substring>. - Don't append outdated threads.
isOutdated: trueusually means the code moved on; verify before spending a fix run on it. - The fixer needs a clean tree, and hard-stops on edits it cannot attribute to
a ledger finding. It exempts
.claude/pr-monitor/pr-*.mdfor exactly this reason — the tracker is dirty on every delegated run. Anything else left uncommitted will stop the fixer and surface as a question. - Suggestion rounds. A poll surfacing only nits/human comments in default mode is a report, not a work order — summarize and wait for the user.
- One PR, one tracker, one loop. Re-invoking on a PR that already has a tracker resumes it; it never starts a parallel monitor.
04 同仓库更多 Skills
writing-design-docs
Use when the user wants to write a problem-statement design doc, says "let's plan a feature properly" / "write a design doc" / "I'm thinking about how to do X" for a non-trivial X, or before committing to a non-obvious technical direction
write-doc
Use when the user asks to write or draft a README, ADR, runbook, tutorial, how-to, explanation, or reference doc, or a caller passes "type ADR" or "type README". Picks the type, fills a template, adds diagrams. RFCs and design docs belong to writing-design-docs.
review-doc
Use when the user asks to review, critique, score, grade, or "how good is this doc" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.
fix-doc
Use when the user asks to fix, edit for prose quality, polish, tighten, humanize, or de-slop a Markdown doc or pasted text, or says "make this read less AI". Applies review-doc findings, generates flagged diagrams, lists substantive issues for the author, then runs the AI-tell pass last. Modifies the target.
create-slides
Use when the user asks for a slide deck, presentation, talk, or slides from a document, report, PR, notes, or topic. Builds one self-contained Machinify-branded HTML deck in a minimalist style, with headline-plus-visual slides, speaker notes, and every diagram drawn by architecture-design:create-diagram.
start-session
Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single /start-session <name>. Use at the START of a session when the user says "start session", "start a worktree", "spin up a worktree for ABC-123", "begin work on <ticket>", or passes a name/ticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude/worktrees/, named exactly after the argument, on a local branch `worktree-<argument>`. Reports what the worktree inherited (`.worktreeinclude` copies, symlinked node_modules) and whether its `.env` still points at the main checkout's stack. If the argument is a JIRA key (e.g. ABC-123, PROJ-1505), also loads that story with the Atlassian CLI (`acli`) when available and summarizes the implementation ask. Also renames the session to the argument (the same effect as `/rename <NAME>`) so it's easy to find in `/resume`. Then stops and waits — it sets up the workspace and context, it does not implement.