[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ASMM252CPZMWPVTER22N1N":3,"skill-same:01M7ASMM252CPZMWPVTER22N1N":53},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":46},"01M7ASMM252CPZMWPVTER22N1N","monitor-pr",null,"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","ozzycodes2\u002Fclaudellum","ozzycodes2","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F21285094?v=4","01M7ASJ57KTP519F96S4QGM7C5","Osniel Quintana","01M7ASJ589JS8S075AA92Y08S4",1,"MIT","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Freview\u002Fskills\u002Fmonitor-pr\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: monitor-pr\ndescription: 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 #45\", \"watch the PR for comments and check failures\", \"address review comments as they come along\", \"keep an eye on CI and fix failures\", or after opening a PR and wanting it shepherded to green. Polls on an interval (drive with \u002Floop), appends each finding to the durable findings ledger, delegates every edit and commit to \u002Freview:fix, pushes what it commits, resolves the bot review threads it addresses, and deletes the tracker once everything is handled. Gates suggestions and human comments for user confirmation instead of acting blindly.\nallowed-tools: Bash Read Write Edit Skill ScheduleWakeup TaskCreate TaskUpdate\ndisable-model-invocation: true\n---\n\n# Monitor PR\n\nShepherd a Claude-authored PR to green without a human babysitting the tab. On a\nrepeating interval, poll the PR for **CI failures** and **new review comments**;\nwhatever is actionable becomes a ledger finding, is fixed and committed by\n`\u002Freview:fix`, is pushed, and — for the bot's own review threads — gets resolved.\nSuggestions and human comments are surfaced for a decision, never silently acted on.\n\n**This skill edits no source file and commits nothing.** It polls, triages,\npushes, and talks to GitHub. Editing is `\u002Freview:fix`'s job.\n\n## Core principles\n\n1. **Baseline, then diff.** Snapshot the PR once at start. On every later tick,\n   act only on what is *new or still-open* versus that baseline — never re-litigate a\n   comment already handled or a check already green. (Learned the hard way:\n   without a baseline the monitor churns on stale findings.)\n2. **One monitor per PR.** Before starting, check for an existing tracker for this PR.\n   If one is active, resume it — do **not** spin up a second loop. Two monitors on one\n   PR means double subagents, double commits, confusion.\n3. **The ledger is the source of truth; the tracker is a mirror.** Finding state\n   lives in `~\u002F.claude\u002Freview-findings\u002F\u003Cowner>__\u003Crepo>\u002Fpr-\u003Cn>.json`, outside the\n   repository and shared with `\u002Freview:fix`. The tracker is the human-readable view\n   of it, carrying the same ledger IDs. When they disagree, the ledger is right.\n4. **Fix what's yours; ask about the rest.** CI failures and the bot's own unresolved\n   review threads are auto-fixed. Human review comments and nit\u002Fsuggestion-level items\n   are logged and reported for the user to decide — pause and ask before acting.\n5. **Delegate the fixing.** Parallelism, partitioning, and the agent contract belong\n   to `\u002Freview:fix`, which owns one lock per ledger and one commit per finding. This\n   skill groups nothing, dispatches nothing, and edits nothing. Append the finding,\n   call the skill, read the result back.\n6. **Respect the permission deny-list** in `shared\u002Ffix-contract.md`, which is the\n   single copy both skills work from. Never `gh pr merge`, never force-push, never\n   `git reset --hard`, never touch the default branch. Fixes are pushed to the *PR\n   branch*. Merging stays with the user; surface the command, don't run it.\n   The one line that differs between the two callers: **`\u002Freview:fix` pushes when\n   invoked directly, but not here — the push is this skill's job.** Phase 2 passes\n   `--no-push` for exactly that reason, and nothing it committed reaches GitHub\n   until Phase 3 runs. Dropping that flag would hand the push to the fixer\n   mid-tick, before this skill has reconciled the tracker.\n\n## Inputs\n\n```\n\u002Fmonitor-pr \u003Cpr-number> [--repo owner\u002Fname] [--auto | --critical-only]\n```\n\n- `\u003Cpr-number>` — required. `--repo` defaults to current repo (`gh repo view`).\n- Default mode: auto-fix **CI failures** + **unresolved bot review threads**; **gate**\n  human comments and suggestions (log + report + ask).\n- `--auto` — also act on human comments and suggestions without pausing.\n- `--critical-only` — act only on CI failures and blocking bot threads; ignore nits.\n\nWork happens in the PR's worktree\u002Fcheckout. If the session isn't already there, check\nout the PR branch first (`gh pr checkout \u003Cn>`); prefer running under a worktree from\n`start-session`.\n\n## The ledger and the tracker\n\n### The ledger — where state lives\n\nThe same file `\u002Freview:review` writes and `\u002Freview:fix` consumes. Resolve its path\nwith the plugin script rather than composing it by hand:\n\n```bash\nPLUGIN_ROOT=\"${CLAUDE_PLUGIN_ROOT:-}\"\nif [ ! -f \"$PLUGIN_ROOT\u002Fscripts\u002Ffindings_ledger.py\" ]; then\n  PLUGIN_ROOT=\"$(cd \"${CLAUDE_SKILL_DIR:-.}\u002F..\u002F..\" 2>\u002Fdev\u002Fnull && pwd)\"\nfi\nLEDGER_PY=\"$PLUGIN_ROOT\u002Fscripts\u002Ffindings_ledger.py\"\nPOLL=\"$PLUGIN_ROOT\u002Fskills\u002Fmonitor-pr\u002Fscripts\u002Fpoll-pr.sh\"\nLEDGER=$(python3 \"$LEDGER_PY\" path --repo \"$REPO\" --pr \"$PR_NUMBER\")\nRUN_ID=\"monitor-$PR_NUMBER-$(date -u +%Y%m%dT%H%M%SZ)\"\n```\n\nBoth paths are absolute on purpose. The working directory is the **reviewed\nrepository**, not this plugin, so a bare `scripts\u002Fpoll-pr.sh` finds nothing — or\nworse, finds a same-named script in the repo under review.\n\n`LEDGER_PY` holds the path only, and `python3` stays at the call site. Folding the\ninterpreter into the variable works in bash and silently breaks in zsh, which does\nnot word-split an unquoted expansion.\n\nThe ledger holds each finding's status, its `external_ref` (the check or thread it came\nfrom), and its `resolved_by_sha` once fixed. It sits outside the repository, so it\nsurvives compaction, `git clean`, and a worktree switch — and it is what lets the\nmonitor and the fixer agree on what is already done.\n\n### The tracker — the human-readable mirror\n\nPath: `.claude\u002Fpr-monitor\u002Fpr-\u003Cn>.md` (create the dir if needed). It exists so a\nperson can read the monitor's state at a glance. It is **not** the store: every row\ncarries the ledger ID it mirrors, and a disagreement is settled by re-reading the\nledger, never by editing the tracker to match a memory.\n\n```markdown\n# PR #\u003Cn> monitor — \u003Cowner\u002Fname>\nbranch: \u003Chead-branch> · mode: \u003Cdefault|auto|critical-only>\nledger: ~\u002F.claude\u002Freview-findings\u002F\u003Cowner>__\u003Crepo>\u002Fpr-\u003Cn>.json\nbaseline @ \u003Cfirst-poll>: checks=\u003Cpass\u002Ffail\u002Fpending> · threads bot=\u003Cn> human=\u003Cn> · reviewDecision=\u003C...>\nlast poll: \u003Cts> · last summary: \u003Cone line>\n\n## Open\n- [ ] F003 · ci · critical · check=\"build (rust)\" · with review:fix\n- [ ] F004 · review-bot · critical · thread=PRRT_x · src.rs:88 · with review:fix\n- [ ] F005 · review-human · needs-decision · thread=PRRT_y · api.ts:12 · REPORTED, awaiting user\n- [ ] F006 · review-bot · deferred by fix · decision: outbox table, CDC, or accept the window?\n\n## Done\n- [x] F001 · ci · check=\"lint\" · \u003Csha> · pushed @ \u003Cts>\n- [x] F002 · review-bot · thread=PRRT_z · \u003Csha> · pushed, thread resolved @ \u003Cts>\n```\n\nRows carry no `owner=agent:…` — this skill owns no agents. A finding in flight is\n\"with review:fix\", and its authoritative status is the ledger's.\n\nRefresh it from `python3 \"$LEDGER_PY\" show` after each phase. **Delete it when Open is empty\nand CI is green** — that is the signal the monitor's job is complete. The ledger\nstays: it is the record of what was fixed, what was deferred, and why.\n\n## Triage matrix\n\n| Signal (from `poll-pr.sh`) | Default | `--auto` | `--critical-only` |\n|---|---|---|---|\n| CI check `failing` | fix | fix | fix |\n| Bot thread, unresolved, blocking\u002Fcritical | fix + resolve | fix + resolve | fix + resolve |\n| Bot thread, nit\u002Fsuggestion | report + ask | fix + resolve | ignore |\n| Human review thread \u002F requested change | report + ask | fix | report + ask |\n| Human issue comment | report + ask | fix | report + ask |\n| `pending` checks | wait (tighten interval) | wait | wait |\n| all green, no open threads | converge → cleanup | converge | converge |\n\n**fix** here means *append to the ledger and let `\u002Freview:fix` do it* — this skill\nnever edits. **report + ask** means the finding is not appended at all; it stays out\nof the ledger until the user says otherwise. **ignore** appends nothing and asks\nnothing.\n\n\"Blocking\u002Fcritical\" vs \"nit\": judge from the comment body and any `reviewDecision:\nCHANGES_REQUESTED`. When unsure, treat a bot thread as fixable and a human thread as\nneeds-decision. Every **fix** in this table implies the Phase 3 acknowledgement — once\nthe fix is pushed, resolve the corresponding thread, or reply @author if it isn't\nresolvable. This applies to human comments too, whenever their fix actually ships.\n\n## Workflow\n\n### Phase 0 — Start \u002F resume (once)\n\n1. If `.claude\u002Fpr-monitor\u002Fpr-\u003Cn>.md` exists → **resume**: read it, then reconcile\n   against the ledger (`python3 \"$LEDGER_PY\" show --ledger \"$LEDGER\" --json`), which is\n   authoritative. Skip re-baselining.\n   Otherwise run `\"$POLL\" \u003Cn> [--repo …]`, write the baseline block, and\n   append every currently-failing check and unresolved actionable thread to the\n   ledger as in Phase 2.\n2. **Check whether a ledger exists.** `\u002Freview:review` writes it; a PR that was\n   never reviewed has none, and Phase 2 will create one with `--create`. A created\n   ledger has an **empty `context` block** — no `test_setup.test_command`, so\n   `\u002Freview:fix` has no local signal and commits unverified, leaning on CI. That is\n   a real limitation, not a detail: say it in the announcement, and suggest\n   `\u002Freview:review \u003Cpr-url>` first when the PR has not been reviewed.\n3. Announce the monitor is live and the cadence, then begin the loop.\n\n### Phase 1 — Poll (each tick)\n\nRun the read-only snapshot:\n\n```bash\n\"$POLL\" \u003Cn> [--repo owner\u002Fname]     # JSON: checks, threads{bot,human}, reviewDecision, mergeStateStatus\n```\n\nDiff against the ledger. New failing checks and newly-unresolved threads become\nfindings to append in Phase 2; checks that went green and threads now\nresolved\u002Foutdated move to `Done` in the tracker. Merged\u002Fclosed PR → stop and clean up.\n\nA finding already in the ledger as `deferred` is **not** new, however the poll looks\n— `\u002Freview:fix` decided a human has to answer it. Leave it where it is.\n\n### Phase 2 — Hand the findings to `\u002Freview:fix`\n\nThis skill writes no file in the repository and makes no commit. It converts what\nthe poll found into ledger entries and calls the fixer.\n\n**1. Append each new actionable finding**, with the `external_ref` that is its\nreturn path to GitHub. Dedupe is the ledger's job — an unresolved thread re-polled\nevery tick appends once.\n\nA failing CI check, piped from the classifier\n(`scripts\u002Freview_formatter.py`'s `classify_ci_failure`):\n\n```bash\nprintf '%s' \"$CI_JSON\" | python3 \"$LEDGER_PY\" append --ledger \"$LEDGER\" --source ci \\\n  --create --pr-url \"$PR_URL\"\n```\n\nAn unresolved review thread, from the `threads` array `poll-pr.sh` already returns:\n\n```bash\nprintf '%s' \"$THREADS_JSON\" | python3 \"$LEDGER_PY\" append --ledger \"$LEDGER\" \\\n  --source review-thread --create --pr-url \"$PR_URL\"\n```\n\n`--create` is a no-op once the ledger exists, so both commands are safe every tick.\n\n**Gated findings are never appended.** A human comment or a nit in default mode\nstays out of the ledger entirely — appending it would hand `\u002Freview:fix` work the\nuser has not approved. Mark it `needs-decision` in the tracker, report it, and ask.\nOnly after the user agrees does it get appended.\n\nTransient CI failures — a timeout, a network blip — classify as `info` and the\nnormalizer drops them. Nothing to fix; the next poll re-runs them.\n\n**2. Call the fixer.**\n\n```\nSkill review:fix \u003Cn> --no-push\n```\n\nIt takes the ledger lock, routes every `open` finding to a strategy, applies it,\nmakes one commit per finding, and runs the suite once per partition — iterating\nuntil the branch is green before it returns. **`--no-push` is required, not\ndecorative:** invoked without it the fixer pushes its own green branch and\nacknowledges its own threads, which would double up with Phase 3.\n\nDo not pass a finding list. Selection is `status == \"open\"`, which is exactly the\nset just appended plus anything an earlier tick could not finish.\n\n**3. Read the result back.**\n\n```bash\npython3 \"$LEDGER_PY\" show --ledger \"$LEDGER\" --status committed,deferred --json\n```\n\nEach `committed` finding carries `resolved_by_sha`; each `deferred` one carries\n`deferral.decision_needed`. Mirror both into the tracker. A deferred finding is a\nquestion for the user, not a retry — re-appending it next tick would loop forever.\n\nIf `\u002Freview:fix` pauses on a finding it could not get to green, it surfaces that\nas a question. Pass it through to the user unchanged; do not re-run the fixer over\nit and do not push a partial result past it.\n\n### Phase 3 — Push, then close the loop\n\n`\u002Freview:fix` left its commits on the local head branch. Nothing has reached GitHub\nyet, so CI has not re-run and no thread can honestly be resolved.\n\n0. **Push the head branch.**\n\n   ```bash\n   git -C \"$WORKTREE\" push origin HEAD\n   ```\n\n   Never `--force`, never `--force-with-lease`, never a refspec naming the default\n   branch. A rejected push means the remote moved: pull with rebase off, inspect,\n   and report — do not resolve any thread, because the fix is not on the PR.\n\n   Push once per tick, after the fixer returns, not once per commit. Each push\n   triggers CI.\n\n1. Mark every finding the push carried `pushed` in the tracker, against its sha.\n2. **Always acknowledge the comment that prompted the work** — non-negotiable once the\n   fix is on the PR branch, for **bot and human** comments alike. The handle is in\n   the finding's `external_ref` (`thread_id`, `comment_id`, `author`), which is why\n   it is recorded at append time and survives the round trip through the fixer.\n\n   **Skip any finding that already carries an `acknowledged` entry for that\n   thread.** `\u002Freview:fix` can also reply and resolve — for work that was already\n   pushed when it ran, or when a user invoked it directly with `--ack-only` — and\n   the ledger is what keeps one reviewer from being answered twice. Record each\n   acknowledgement the same way:\n\n   ```bash\n   python3 \"$LEDGER_PY\" ack --ledger \"$LEDGER\" --id \u003CID> --thread \u003Cthread_id> \\\n     --action reply+resolve --run \"$RUN_ID\"\n   ```\n\n   A **deferred** finding gets a reply stating the decision it needs, and the\n   thread stays **open**. Resolving it would hide the one finding that most needs\n   a human.\n   - **Inline \u002F resolvable review thread** → resolve it:\n     ```bash\n     gh api graphql -f query='mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread{ isResolved } } }' -F id=\"\u003CthreadId>\"\n     ```\n   - **Not inline \u002F not resolvable** (a PR-level issue comment, or any comment with no\n     resolve handle) → reply with a **new comment that @-mentions the original author**\n     and points at the fix:\n     ```bash\n     gh pr comment \u003Cn> --body \"@\u003Cauthor> addressed in \u003Csha> — \u003Cone-line of what changed>.\"\n     ```\n     To reply *inside* an existing review thread instead of at PR level:\n     ```bash\n     gh api repos\u002F\u003Cowner>\u002F\u003Crepo>\u002Fpulls\u002F\u003Cn>\u002Fcomments\u002F\u003Ccomment-id>\u002Freplies -f body=\"@\u003Cauthor> addressed in \u003Csha> — …\"\n     ```\n3. Let CI re-run; the next poll confirms green or surfaces a follow-up failure.\n\n### Phase 4 — Converge and clean up\n\nWhen `Open` is empty **and** CI is green **and** no unresolved actionable threads\nremain:\n\n- Post\u002Fkeep a short summary: what was fixed, what was pushed, what still needs the user\n  (gated items, deferrals from `\u002Freview:fix`, merge).\n- **Delete the tracker** `.claude\u002Fpr-monitor\u002Fpr-\u003Cn>.md`. **Keep the ledger** — it\n  records what was fixed and what was deferred, and a reopened PR resumes from it.\n- Release the fixer's lock if a killed run left one:\n\n  ```bash\n  python3 \"$LEDGER_PY\" unlock --ledger \"$LEDGER\"\n  ```\n- Stop scheduling further ticks. If `mergeStateStatus` is `BLOCKED` only on approval,\n  say so — do not attempt the merge.\n\n## Cadence — drive with `\u002Floop`\n\nBuilt to run as a loop. Drive it with the **`\u002Floop`** skill: each firing\nre-enters and runs one Phase 1→3 tick. Under the hood that uses `ScheduleWakeup` for\ndynamic pacing — if you aren't launched via `\u002Floop`, self-schedule the next tick with\n`ScheduleWakeup`.\n\nPick the interval by what you're waiting on (align to the prompt-cache window):\n\n- **CI running \u002F fixes in flight** → ~**240s** (checks resolve in minutes; stays cache-warm).\n- **Idle, awaiting human review** → ~**1200–1800s** (nothing changes minute-to-minute).\n- Stop the loop entirely at Phase 4, or if the PR is merged\u002Fclosed.\n\nAlways pass the same `\u002Fmonitor-pr \u003Cn>` prompt back so the next firing repeats the tick.\n\n## Gotchas\n\n- **No `Agent` in `allowed-tools`, deliberately.** Dispatch belongs to `\u002Freview:fix`,\n  which pins `subagent_type` *and* `model` per strategy. An agent launched from here\n  would inherit the session model and commit from a second `.git\u002Findex`.\n- **Deferred tools.** `ScheduleWakeup` is native. If you track in-flight work with\n  `TaskCreate`\u002F`TaskUpdate`, the **ledger** stays the source of truth (it survives\n  compaction; task state may not).\n- **`poll-pr.sh` mutates nothing.** It only reads. Appending, pushing, and thread\n  resolution are your job, per the matrix; editing and committing are not.\n- **Bot detection.** The script flags authors containing `claude-code-action` or ending\n  `[bot]` as bots. If this repo's Claude reviewer uses a different login, pass it via\n  `CLAUDE_BOT=\u003Csubstring>`.\n- **Don't append outdated threads.** `isOutdated: true` usually means the code moved\n  on; verify before spending a fix run on it.\n- **The fixer needs a clean tree**, and hard-stops on edits it cannot attribute to\n  a ledger finding. It exempts `.claude\u002Fpr-monitor\u002Fpr-*.md` for exactly this\n  reason — the tracker is dirty on every delegated run. Anything *else* left\n  uncommitted will stop the fixer and surface as a question.\n- **Suggestion rounds.** A poll surfacing only nits\u002Fhuman comments in default mode is\n  a *report*, not a work order — summarize and wait for the user.\n- **One PR, one tracker, one loop.** Re-invoking on a PR that already has a tracker\n  resumes it; it never starts a parallel monitor.\n","# Monitor PR\n\nShepherd a Claude-authored PR to green without a human babysitting the tab. On a\nrepeating interval, poll the PR for **CI failures** and **new review comments**;\nwhatever is actionable becomes a ledger finding, is fixed and committed by\n`\u002Freview:fix`, is pushed, and — for the bot's own review threads — gets resolved.\nSuggestions and human comments are surfaced for a decision, never silently acted on.\n\n**This skill edits no source file and commits nothing.** It polls, triages,\npushes, and talks to GitHub. Editing is `\u002Freview:fix`'s job.\n\n## Core principles\n\n1. **Baseline, then diff.** Snapshot the PR once at start. On every later tick,\n   act only on what is *new or still-open* versus that baseline — never re-litigate a\n   comment already handled or a check already green. (Learned the hard way:\n   without a baseline the monitor churns on stale findings.)\n2. **One monitor per PR.** Before starting, check for an existing tracker for this PR.\n   If one is active, resume it — do **not** spin up a second loop. Two monitors on one\n   PR means double subagents, double commits, confusion.\n3. **The ledger is the source of truth; the tracker is a mirror.** Finding state\n   lives in `~\u002F.claude\u002Freview-findings\u002F\u003Cowner>__\u003Crepo>\u002Fpr-\u003Cn>.json`, outside the\n   repository and shared with `\u002Freview:fix`. The tracker is the human-readable view\n   of it, carrying the same ledger IDs. When they disagree, the ledger is right.\n4. **Fix what's yours; ask about the rest.** CI failures and the bot's own unresolved\n   review threads are auto-fixed. Human review comments and nit\u002Fsuggestion-level items\n   are logged and reported for the user to decide — pause and ask before acting.\n5. **Delegate the fixing.** Parallelism, partitioning, and the agent contract belong\n   to `\u002Freview:fix`, which owns one lock per ledger and one commit per finding. This\n   skill groups nothing, dispatches nothing, and edits nothing. Append the finding,\n   call the skill, read the result back.\n6. **Respect the permission deny-list** in `shared\u002Ffix-contract.md`, which is the\n   single copy both skills work from. Never `gh pr merge`, never force-push, never\n   `git reset --hard`, never touch the default branch. Fixes are pushed to the *PR\n   branch*. Merging stays with the user; surface the command, don't run it.\n   The one line that differs between the two callers: **`\u002Freview:fix` pushes when\n   invoked directly, but not here — the push is this skill's job.** Phase 2 passes\n   `--no-push` for exactly that reason, and nothing it committed reaches GitHub\n   until Phase 3 runs. Dropping that flag would hand the push to the fixer\n   mid-tick, before this skill has reconciled the tracker.\n\n## Inputs\n\n```\n\u002Fmonitor-pr \u003Cpr-number> [--repo owner\u002Fname] [--auto | --critical-only]\n```\n\n- `\u003Cpr-number>` — required. `--repo` defaults to current repo (`gh repo view`).\n- Default mode: auto-fix **CI failures** + **unresolved bot review threads**; **gate**\n  human comments and suggestions (log + report + ask).\n- `--auto` — also act on human comments and suggestions without pausing.\n- `--critical-only` — act only on CI failures and blocking bot threads; ignore nits.\n\nWork happens in the PR's worktree\u002Fcheckout. If the session isn't already there, check\nout the PR branch first (`gh pr checkout \u003Cn>`); prefer running under a worktree from\n`start-session`.\n\n## The ledger and the tracker\n\n### The ledger — where state lives\n\nThe same file `\u002Freview:review` writes and `\u002Freview:fix` consumes. Resolve its path\nwith the plugin script rather than composing it by hand:\n\n```bash\nPLUGIN_ROOT=\"${CLAUDE_PLUGIN_ROOT:-}\"\nif [ ! -f \"$PLUGIN_ROOT\u002Fscripts\u002Ffindings_ledger.py\" ]; then\n  PLUGIN_ROOT=\"$(cd \"${CLAUDE_SKILL_DIR:-.}\u002F..\u002F..\" 2>\u002Fdev\u002Fnull && pwd)\"\nfi\nLEDGER_PY=\"$PLUGIN_ROOT\u002Fscripts\u002Ffindings_ledger.py\"\nPOLL=\"$PLUGIN_ROOT\u002Fskills\u002Fmonitor-pr\u002Fscripts\u002Fpoll-pr.sh\"\nLEDGER=$(python3 \"$LEDGER_PY\" path --repo \"$REPO\" --pr \"$PR_NUMBER\")\nRUN_ID=\"monitor-$PR_NUMBER-$(date -u +%Y%m%dT%H%M%SZ)\"\n```\n\nBoth paths are absolute on purpose. The working directory is the **reviewed\nrepository**, not this plugin, so a bare `scripts\u002Fpoll-pr.sh` finds nothing — or\nworse, finds a same-named script in the repo under review.\n\n`LEDGER_PY` holds the path only, and `python3` stays at the call site. Folding the\ninterpreter into the variable works in bash and silently breaks in zsh, which does\nnot word-split an unquoted expansion.\n\nThe ledger holds each finding's status, its `external_ref` (the check or thread it came\nfrom), and its `resolved_by_sha` once fixed. It sits outside the repository, so it\nsurvives compaction, `git clean`, and a worktree switch — and it is what lets the\nmonitor and the fixer agree on what is already done.\n\n### The tracker — the human-readable mirror\n\nPath: `.claude\u002Fpr-monitor\u002Fpr-\u003Cn>.md` (create the dir if needed). It exists so a\nperson can read the monitor's state at a glance. It is **not** the store: every row\ncarries the ledger ID it mirrors, and a disagreement is settled by re-reading the\nledger, never by editing the tracker to match a memory.\n\n```markdown\n# PR #\u003Cn> monitor — \u003Cowner\u002Fname>\nbranch: \u003Chead-branch> · mode: \u003Cdefault|auto|critical-only>\nledger: ~\u002F.claude\u002Freview-findings\u002F\u003Cowner>__\u003Crepo>\u002Fpr-\u003Cn>.json\nbaseline @ \u003Cfirst-poll>: checks=\u003Cpass\u002Ffail\u002Fpending> · threads bot=\u003Cn> human=\u003Cn> · reviewDecision=\u003C...>\nlast poll: \u003Cts> · last summary: \u003Cone line>\n\n## Open\n- [ ] F003 · ci · critical · check=\"build (rust)\" · with review:fix\n- [ ] F004 · review-bot · critical · thread=PRRT_x · src.rs:88 · with review:fix\n- [ ] F005 · review-human · needs-decision · thread=PRRT_y · api.ts:12 · REPORTED, awaiting user\n- [ ] F006 · review-bot · deferred by fix · decision: outbox table, CDC, or accept the window?\n\n## Done\n- [x] F001 · ci · check=\"lint\" · \u003Csha> · pushed @ \u003Cts>\n- [x] F002 · review-bot · thread=PRRT_z · \u003Csha> · pushed, thread resolved @ \u003Cts>\n```\n\nRows carry no `owner=agent:…` — this skill owns no agents. A finding in flight is\n\"with review:fix\", and its authoritative status is the ledger's.\n\nRefresh it from `python3 \"$LEDGER_PY\" show` after each phase. **Delete it when Open is empty\nand CI is green** — that is the signal the monitor's job is complete. The ledger\nstays: it is the record of what was fixed, what was deferred, and why.\n\n## Triage matrix\n\n| Signal (from `poll-pr.sh`) | Default | `--auto` | `--critical-only` |\n|---|---|---|---|\n| CI check `failing` | fix | fix | fix |\n| Bot thread, unresolved, blocking\u002Fcritical | fix + resolve | fix + resolve | fix + resolve |\n| Bot thread, nit\u002Fsuggestion | report + ask | fix + resolve | ignore |\n| Human review thread \u002F requested change | report + ask | fix | report + ask |\n| Human issue comment | report + ask | fix | report + ask |\n| `pending` checks | wait (tighten interval) | wait | wait |\n| all green, no open threads | converge → cleanup | converge | converge |\n\n**fix** here means *append to the ledger and let `\u002Freview:fix` do it* — this skill\nnever edits. **report + ask** means the finding is not appended at all; it stays out\nof the ledger until the user says otherwise. **ignore** appends nothing and asks\nnothing.\n\n\"Blocking\u002Fcritical\" vs \"nit\": judge from the comment body and any `reviewDecision:\nCHANGES_REQUESTED`. When unsure, treat a bot thread as fixable and a human thread as\nneeds-decision. Every **fix** in this table implies the Phase 3 acknowledgement — once\nthe fix is pushed, resolve the corresponding thread, or reply @author if it isn't\nresolvable. This applies to human comments too, whenever their fix actually ships.\n\n## Workflow\n\n### Phase 0 — Start \u002F resume (once)\n\n1. If `.claude\u002Fpr-monitor\u002Fpr-\u003Cn>.md` exists → **resume**: read it, then reconcile\n   against the ledger (`python3 \"$LEDGER_PY\" show --ledger \"$LEDGER\" --json`), which is\n   authoritative. Skip re-baselining.\n   Otherwise run `\"$POLL\" \u003Cn> [--repo …]`, write the baseline block, and\n   append every currently-failing check and unresolved actionable thread to the\n   ledger as in Phase 2.\n2. **Check whether a ledger exists.** `\u002Freview:review` writes it; a PR that was\n   never reviewed has none, and Phase 2 will create one with `--create`. A created\n   ledger has an **empty `context` block** — no `test_setup.test_command`, so\n   `\u002Freview:fix` has no local signal and commits unverified, leaning on CI. That is\n   a real limitation, not a detail: say it in the announcement, and suggest\n   `\u002Freview:review \u003Cpr-url>` first when the PR has not been reviewed.\n3. Announce the monitor is live and the cadence, then begin the loop.\n\n### Phase 1 — Poll (each tick)\n\nRun the read-only snapshot:\n\n```bash\n\"$POLL\" \u003Cn> [--repo owner\u002Fname]     # JSON: checks, threads{bot,human}, reviewDecision, mergeStateStatus\n```\n\nDiff against the ledger. New failing checks and newly-unresolved threads become\nfindings to append in Phase 2; checks that went green and threads now\nresolved\u002Foutdated move to `Done` in the tracker. Merged\u002Fclosed PR → stop and clean up.\n\nA finding already in the ledger as `deferred` is **not** new, however the poll looks\n— `\u002Freview:fix` decided a human has to answer it. Leave it where it is.\n\n### Phase 2 — Hand the findings to `\u002Freview:fix`\n\nThis skill writes no file in the repository and makes no commit. It converts what\nthe poll found into ledger entries and calls the fixer.\n\n**1. Append each new actionable finding**, with the `external_ref` that is its\nreturn path to GitHub. Dedupe is the ledger's job — an unresolved thread re-polled\nevery tick appends once.\n\nA failing CI check, piped from the classifier\n(`scripts\u002Freview_formatter.py`'s `classify_ci_failure`):\n\n```bash\nprintf '%s' \"$CI_JSON\" | python3 \"$LEDGER_PY\" append --ledger \"$LEDGER\" --source ci \\\n  --create --pr-url \"$PR_URL\"\n```\n\nAn unresolved review thread, from the `threads` array `poll-pr.sh` already returns:\n\n```bash\nprintf '%s' \"$THREADS_JSON\" | python3 \"$LEDGER_PY\" append --ledger \"$LEDGER\" \\\n  --source review-thread --create --pr-url \"$PR_URL\"\n```\n\n`--create` is a no-op once the ledger exists, so both commands are safe every tick.\n\n**Gated findings are never appended.** A human comment or a nit in default mode\nstays out of the ledger entirely — appending it would hand `\u002Freview:fix` work the\nuser has not approved. Mark it `needs-decision` in the tracker, report it, and ask.\nOnly after the user agrees does it get appended.\n\nTransient CI failures — a timeout, a network blip — classify as `info` and the\nnormalizer drops them. Nothing to fix; the next poll re-runs them.\n\n**2. Call the fixer.**\n\n```\nSkill review:fix \u003Cn> --no-push\n```\n\nIt takes the ledger lock, routes every `open` finding to a strategy, applies it,\nmakes one commit per finding, and runs the suite once per partition — iterating\nuntil the branch is green before it returns. **`--no-push` is required, not\ndecorative:** invoked without it the fixer pushes its own green branch and\nacknowledges its own threads, which would double up with Phase 3.\n\nDo not pass a finding list. Selection is `status == \"open\"`, which is exactly the\nset just appended plus anything an earlier tick could not finish.\n\n**3. Read the result back.**\n\n```bash\npython3 \"$LEDGER_PY\" show --ledger \"$LEDGER\" --status committed,deferred --json\n```\n\nEach `committed` finding carries `resolved_by_sha`; each `deferred` one carries\n`deferral.decision_needed`. Mirror both into the tracker. A deferred finding is a\nquestion for the user, not a retry — re-appending it next tick would loop forever.\n\nIf `\u002Freview:fix` pauses on a finding it could not get to green, it surfaces that\nas a question. Pass it through to the user unchanged; do not re-run the fixer over\nit and do not push a partial result past it.\n\n### Phase 3 — Push, then close the loop\n\n`\u002Freview:fix` left its commits on the local head branch. Nothing has reached GitHub\nyet, so CI has not re-run and no thread can honestly be resolved.\n\n0. **Push the head branch.**\n\n   ```bash\n   git -C \"$WORKTREE\" push origin HEAD\n   ```\n\n   Never `--force`, never `--force-with-lease`, never a refspec naming the default\n   branch. A rejected push means the remote moved: pull with rebase off, inspect,\n   and report — do not resolve any thread, because the fix is not on the PR.\n\n   Push once per tick, after the fixer returns, not once per commit. Each push\n   triggers CI.\n\n1. Mark every finding the push carried `pushed` in the tracker, against its sha.\n2. **Always acknowledge the comment that prompted the work** — non-negotiable once the\n   fix is on the PR branch, for **bot and human** comments alike. The handle is in\n   the finding's `external_ref` (`thread_id`, `comment_id`, `author`), which is why\n   it is recorded at append time and survives the round trip through the fixer.\n\n   **Skip any finding that already carries an `acknowledged` entry for that\n   thread.** `\u002Freview:fix` can also reply and resolve — for work that was already\n   pushed when it ran, or when a user invoked it directly with `--ack-only` — and\n   the ledger is what keeps one reviewer from being answered twice. Record each\n   acknowledgement the same way:\n\n   ```bash\n   python3 \"$LEDGER_PY\" ack --ledger \"$LEDGER\" --id \u003CID> --thread \u003Cthread_id> \\\n     --action reply+resolve --run \"$RUN_ID\"\n   ```\n\n   A **deferred** finding gets a reply stating the decision it needs, and the\n   thread stays **open**. Resolving it would hide the one finding that most needs\n   a human.\n   - **Inline \u002F resolvable review thread** → resolve it:\n     ```bash\n     gh api graphql -f query='mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread{ isResolved } } }' -F id=\"\u003CthreadId>\"\n     ```\n   - **Not inline \u002F not resolvable** (a PR-level issue comment, or any comment with no\n     resolve handle) → reply with a **new comment that @-mentions the original author**\n     and points at the fix:\n     ```bash\n     gh pr comment \u003Cn> --body \"@\u003Cauthor> addressed in \u003Csha> — \u003Cone-line of what changed>.\"\n     ```\n     To reply *inside* an existing review thread instead of at PR level:\n     ```bash\n     gh api repos\u002F\u003Cowner>\u002F\u003Crepo>\u002Fpulls\u002F\u003Cn>\u002Fcomments\u002F\u003Ccomment-id>\u002Freplies -f body=\"@\u003Cauthor> addressed in \u003Csha> — …\"\n     ```\n3. Let CI re-run; the next poll confirms green or surfaces a follow-up failure.\n\n### Phase 4 — Converge and clean up\n\nWhen `Open` is empty **and** CI is green **and** no unresolved actionable threads\nremain:\n\n- Post\u002Fkeep a short summary: what was fixed, what was pushed, what still needs the user\n  (gated items, deferrals from `\u002Freview:fix`, merge).\n- **Delete the tracker** `.claude\u002Fpr-monitor\u002Fpr-\u003Cn>.md`. **Keep the ledger** — it\n  records what was fixed and what was deferred, and a reopened PR resumes from it.\n- Release the fixer's lock if a killed run left one:\n\n  ```bash\n  python3 \"$LEDGER_PY\" unlock --ledger \"$LEDGER\"\n  ```\n- Stop scheduling further ticks. If `mergeStateStatus` is `BLOCKED` only on approval,\n  say so — do not attempt the merge.\n\n## Cadence — drive with `\u002Floop`\n\nBuilt to run as a loop. Drive it with the **`\u002Floop`** skill: each firing\nre-enters and runs one Phase 1→3 tick. Under the hood that uses `ScheduleWakeup` for\ndynamic pacing — if you aren't launched via `\u002Floop`, self-schedule the next tick with\n`ScheduleWakeup`.\n\nPick the interval by what you're waiting on (align to the prompt-cache window):\n\n- **CI running \u002F fixes in flight** → ~**240s** (checks resolve in minutes; stays cache-warm).\n- **Idle, awaiting human review** → ~**1200–1800s** (nothing changes minute-to-minute).\n- Stop the loop entirely at Phase 4, or if the PR is merged\u002Fclosed.\n\nAlways pass the same `\u002Fmonitor-pr \u003Cn>` prompt back so the next firing repeats the tick.\n\n## Gotchas\n\n- **No `Agent` in `allowed-tools`, deliberately.** Dispatch belongs to `\u002Freview:fix`,\n  which pins `subagent_type` *and* `model` per strategy. An agent launched from here\n  would inherit the session model and commit from a second `.git\u002Findex`.\n- **Deferred tools.** `ScheduleWakeup` is native. If you track in-flight work with\n  `TaskCreate`\u002F`TaskUpdate`, the **ledger** stays the source of truth (it survives\n  compaction; task state may not).\n- **`poll-pr.sh` mutates nothing.** It only reads. Appending, pushing, and thread\n  resolution are your job, per the matrix; editing and committing are not.\n- **Bot detection.** The script flags authors containing `claude-code-action` or ending\n  `[bot]` as bots. If this repo's Claude reviewer uses a different login, pass it via\n  `CLAUDE_BOT=\u003Csubstring>`.\n- **Don't append outdated threads.** `isOutdated: true` usually means the code moved\n  on; verify before spending a fix run on it.\n- **The fixer needs a clean tree**, and hard-stops on edits it cannot attribute to\n  a ledger finding. It exempts `.claude\u002Fpr-monitor\u002Fpr-*.md` for exactly this\n  reason — the tracker is dirty on every delegated run. Anything *else* left\n  uncommitted will stop the fixer and surface as a question.\n- **Suggestion rounds.** A poll surfacing only nits\u002Fhuman comments in default mode is\n  a *report*, not a work order — summarize and wait for the user.\n- **One PR, one tracker, one loop.** Re-invoking on a PR that already has a tracker\n  resumes it; it never starts a parallel monitor.\n",{"name":5,"description":7,"allowed-tools":24,"disable-model-invocation":25},"Bash Read Write Edit Skill ScheduleWakeup TaskCreate TaskUpdate",true,"main","a3f19bcc313571bff79dca391a83f9c4d38bb335","review\u002Fskills\u002Fmonitor-pr",0,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum","https:\u002F\u002Fgithub.com\u002Fozzycodes2","Software Engineer | Engineering Manager | AI whisperer | ☕Enjoyer","2026-11-14 04:50:11",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":25},[36,39,42],{"tool":37,"command":38},"npx","npx skills add ozzycodes2\u002Fclaudellum --skill monitor-pr",{"tool":40,"command":41},"bunx","bunx skills add ozzycodes2\u002Fclaudellum --skill monitor-pr",{"tool":43,"command":44},"pnpm","pnpm dlx skills add ozzycodes2\u002Fclaudellum --skill monitor-pr","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Freview\u002Fskills\u002Fmonitor-pr\u002FSKILL.md",[47],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"scripts\u002Fpoll-pr.sh","SCRIPT","脚本",4864,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Freview\u002Fskills\u002Fmonitor-pr\u002Fscripts\u002Fpoll-pr.sh",[54,61,68,75,82,89],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M7ASQB3CTKMKDNAXD9DCF1YC","writing-design-docs","Use when the user wants to write a problem-statement design doc, says \"let's plan a feature properly\" \u002F \"write a design doc\" \u002F \"I'm thinking about how to do X\" for a non-trivial X, or before committing to a non-obvious technical direction","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwriting-design-docs\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M7ASQ6JD4QRV5ZKK2QME401Y","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.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwrite-doc\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7ASQ1VWNVP1RE7M5D4G2QMG","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.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Freview-doc\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7ASPWST208JZNR7HF7J6KMV","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.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Ffix-doc\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7ASPS6Y9ZGK9KCDHNPDR75A","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.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fcreate-slides\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7ASPAKFY045KHR92Y4QFTWV","start-session","Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single \u002Fstart-session \u003Cname>. 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 \u003Cticket>\", or passes a name\u002Fticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude\u002Fworktrees\u002F, named exactly after the argument, on a local branch `worktree-\u003Cargument>`. 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 `\u002Frename \u003CNAME>`) so it's easy to find in `\u002Fresume`. Then stops and waits — it sets up the workspace and context, it does not implement.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Fsession-mgmt\u002Fskills\u002Fstart-session\u002FSKILL.md",[],[]]