Tadashi Shigeoka· Tue, November 17, 2026
The ht-pr-approve skill I wrote last time takes one PR URL and a natural-language policy, runs four reviews from Claude Code and Codex inside a disposable git worktree, and submits a single commit-bound approval through the GitHub Pull Request Review API when the policy passes with no P0 findings. The gap it left open was that my account keeps accumulating review requests, so clearing them with that skill still meant running it by hand one PR at a time, feeding the same repository and the same policy into it over and over.
I added ht-pr-approve-loop to hermes-talaria to close that outer loop. The pull request is codenote-net/hermes-talaria#65. Given one explicit repository, the new skill freezes all open PRs matching is:pr state:open user-review-requested:@me sort:created-asc as an oldest-first snapshot, reuses the existing ht-pr-approve runner for every PR, and submits exactly one 👌 approval for each PR whose four-review adjudication shows no P0 findings. This post walks through the design decisions I had to make to close that loop safely.
Shape of the skill #
ht-pr-approve-loop accepts either a repository URL or the equivalent encoded pulls-search URL, and nothing else:
The literal query the helper builds is pinned to:
The minimal set of rules I chose for the loop is:
- The target repository is only ever the one explicitly supplied on the command line. No inference from the current directory, Organization, or account.
user-review-requested:@memeans a request addressed to the authenticated user personally, not through a team. The loop never substitutesreview-requested,team-review-requested,is:open, or a guessed username.- The only public write is one API review with
event: APPROVE,body: "👌", and a pinnedcommit_id. No separate comment, fix, merge, retry, or recurring job. - The approval predicate is “no P0 findings” and nothing else. P1, P2, and P3 findings land in the private ledger but do not block approval.
The skill runs in five stages. Stage three calls the existing ht-pr-approve runner directly for each PR’s reviews, so the loop itself owns discovery and freezing, per-PR rechecks, adjudication of the four reviews, and aggregation.
flowchart TD
IN[repo URL or pulls search URL] --> DISC[discover_prs.py<br/>paginates GitHub search exhaustively]
DISC -->|incomplete_results false<br/>total_count stable<br/>< 1000| SNAP[frozen snapshot JSON<br/>oldest-first]
SNAP --> LOOP{one frozen URL at a time}
LOOP --> ELIG[recheck direct request, state, draft, author, head/base]
ELIG -->|OK| REUSE[call ht-pr-approve's review_pr.py]
ELIG -->|mismatch| SKIPE[skip this PR]
REUSE --> ADJ[agent adjudicates the four reviews<br/>no P0?]
ADJ -->|PASS| PRE[refresh head/base and request right before POST]
ADJ -->|FAIL / UNKNOWN| SKIPP[skip this PR]
PRE -->|mismatch| STALE[record as stale and skip]
PRE -->|match| POST[gh api POST with pinned commit_id<br/>body is 👌]
POST --> VERIFY[read the review back<br/>match reviewer, state, commit_id, body]
VERIFY --> LOOP
LOOP --> REPORT[private aggregated report]
Forcing the repository to be explicit #
The first design call for the loop was to never guess the scope. If /ht-pr-approve-loop is invoked without a repository URL, the skill asks instead of pulling the Git remote of the current directory or picking the most recent Organization the agent touched. SKILL.md puts it as:
Without an explicit repository target, ask rather than inferring one from the current directory, organization, or account. Never expand the scope.
Two reasons sit behind that choice. The first is that user-review-requested:@me targets the authenticated user across all of GitHub, so widening the scope lets the agent reach into Organizations the caller did not mean to touch. The second is that in repositories where branch protection sets required approvals, an approval can make a PR merge-ready, and even when the final merge call still belongs to a human, letting approvals quietly spread across many repositories enlarges the set of PRs sitting at merge-ready state. Confining a single invocation to a single repository keeps that set small.
URL parsing is just as strict. urlsplit plus fullmatch rejects a q that includes an additional repo: qualifier, unknown scopes, alternate hosts, fragments, or trailing slashes with a ValueError instead of quietly repairing anything. Only https://github.com/OWNER/REPO or a /pulls URL whose single q parameter equals the fixed query is accepted.
Exhausting pagination before the loop starts #
Discovery lives in a single Python helper, scripts/discover_prs.py, which only reads GitHub. The helper never approves, never asks the model for anything, and never writes outside the external run directory. It calls the GitHub search/issues API with per_page=100, walks pages starting from 1, and refuses to treat an incomplete fetch as a usable snapshot. Three separate checks encode that refusal:
- Each page must report
incomplete_resultsas explicitlyfalse, otherwiseValueError. - The
total_counton page two and later must match page one exactly, otherwiseValueError. - A
total_countat or above 1000 is rejected because that is where the search API caps results.
Once total_count reaches the search cap, a complete oldest-first result is no longer guaranteed, so running the loop over a truncated result set is worse than having no snapshot at all. The stable-total check stops discovery without a snapshot when the count visibly changes mid-pagination. It is not a full guarantee, though: a paginated search is not an atomic server snapshot, and an unchanged total cannot prove the result set itself is unchanged. The snapshot therefore only freezes the candidates the helper observed, and every PR is rechecked live right before it is processed.
The snapshot is written to an external run directory outside every checkout, with an exclusive x mode open and exists / is_symlink / parents checks that refuse to write inside the source tree or over an existing file. Ledger entries, per-PR evidence JSON, and approval payloads live in the same external directory. That one placement rule keeps private evaluation data out of Git in a single sweep.
Separating direct and team review requests #
user-review-requested:@me scopes the query to review requests addressed to the authenticated user personally. Team-addressed requests have their own qualifier, team-review-requested, and the loop refuses to merge the two. SKILL.md spells it out:
user-review-requested:@me means a request addressed directly to the authenticated user, not a team request. Never replace it with review-requested, team-review-requested, is:open, or a guessed username.
On top of that query, the loop refuses to trust search index membership alone as proof of eligibility. Right before every POST, it paginates GET /repos/OWNER/REPO/pulls/NUMBER/requested_reviewers all the way to the end and verifies that the authenticated login is present in the current users list. A match in teams only is not enough. If the search index happens to surface a team request, or if the request is withdrawn between discovery and submission, the latest state from requested_reviewers wins. A direct request from a human and a team-wide ping are different weights of ask, so the loop does not silently approve the second kind.
Re-reading state right before POST #
A snapshot is a point-in-time photo, and PR state can shift between discovery and the end of the review. The loop refreshes PR state twice for each candidate:
- Right after pulling one URL off the snapshot, before any review runs.
- Right after the four reviews pass adjudication, before the API submission.
The second refresh reads pulls/{number} and paginates requested_reviewers and reviews in full, and requires every one of these checks to still hold:
- The repository and reviewer login match the discovery-time values.
state == openanddraft == false.- The author is still different from the reviewer.
- The authenticated login still appears in
requested_reviewers.users. - The pinned head SHA and base SHA still match the current pair.
If either the head or the base has moved, the loop refuses to roll into “review and approve the new pair in this same pass.” Fresh code requires fresh evidence, so the PR is recorded as stale and the loop moves on without a silent head slide.
Reusing the runner and making room for a 👌 body #
Stage three calls the existing ht-pr-approve runner (scripts/review_pr.py) as-is. Keeping the four-review runner in one place meant I did not have to reimplement inside the loop how the reviews are run against the pinned head/base and how their raw outputs are recorded. The invocation is a one-liner from the loop’s point of view:
The one thing I did change on the ht-pr-approve side was the public body. Previously it was always a detailed English prose block covering policy, evidence, counts, and rationale. That body is useful on a one-off approval, but pasted verbatim onto every PR in a batch it turns into notification noise. So I added a narrow seam: the caller can supply an exact custom body, and only the public body is replaced. SKILL.md captures the rule:
An explicitly supplied exact custom approval body overrides only the public body, not the review, policy, freshness, or verification gates. Preserve it exactly, including Unicode and whitespace; do not append explanations or a newline.
Policy interpretation, freshness checks, and read-back verification all continue to run as before. The private ledger still records the full policy text, reviewed pair, evidence, and finding counts. The loop uses that seam to pass 👌 (U+1F44C, a single character with no newline and no trailing whitespace), and read-back verifies byte-level equality with 👌.
Shrinking the public body does not shrink the information I keep for myself. P1, P2, and P3 findings, raw model reports, and adjudication notes all land in the private ledger for later per-PR review on my end.
Grounding idempotency in the ledger, not in the body #
Idempotency against an already-APPROVED PR cannot be closed by a 👌 body match. Some other run, some other policy, or some other reviewer could have pushed the same emoji; worse, an older APPROVED review at the same head could have been superseded by a later CHANGES_REQUESTED or dismissal. SKILL.md is explicit:
Never accept an arbitrary historic APPROVED: account for later effective CHANGES_REQUESTED, dismissal, or other superseding decision state. … The emoji alone proves neither policy equivalence nor review completion.
The loop only records an already_approved no-op when all four of these conditions hold:
- There is a currently effective, non-dismissed APPROVED review at the same head.
- The external ledger has an entry that binds that review ID to the exact reviewer, body, head/base pair, complete four-review evidence, no-P0 adjudication record, and policy string.
- That ledger entry’s policy is equivalent to the current invocation’s policy (both “no P0 findings”).
- Reading the review ID back from the API returns a payload that matches the ledger.
When any of those is missing, the loop writes duplicate_ambiguous and skips the PR without pushing a second approval. Treating “same emoji at the same head” as proof would let a 👌 from some earlier context pass for a successful outcome of this run, which collapses the audit trail. Keeping the public body out of the proof chain keeps the boundary between “same byte sequence” and “same policy decision” visible.
Stopping the loop when the outcome is ambiguous #
The other explicit loop behavior is that any ambiguity around submission stops the entire run and leaves the remaining candidates untouched. A POST that times out before the response is known, a read-back whose reviewer / state / commit / body differs from what the loop meant to send, or a reconciliation that returns multiple plausible matches all cause submission_unknown to be persisted and no further PRs to be attempted.
If acceptance or read-back cannot be established, persist submission_unknown and stop the entire loop; leave remaining candidates unattempted.
Halting is the cheaper path here. Blind retries after an ambiguous submission risk a duplicate approval on the same head or, worse, on a head that already changed; stopping and reading the review history once by hand is a small, bounded cost. Authentication failures and rate-limit errors get the same treatment: they are not demoted to per-PR skips, because leaving the remaining PRs sitting in the snapshot for the next human to pick up is strictly better than pushing partial state onto GitHub.
Known limitation and what comes next #
The discovery helper compares the repository_url returned by the GitHub search/issues API with the supplied repository using a case-sensitive string match. GitHub itself accepts owner and name case-insensitively, so invoking the loop as https://github.com/Example/Project is rejected once the API responds with the canonical example/project. The workaround is to use the canonical spelling. This behavior is recorded as a P2 in the validation matrix without an automatic fix, because the failure mode is “reject a valid repository,” not “approve something out of scope.”
I held off on a normalization pass because I first want to confirm whether the shape of repository_url is stable in the API contract and whether GitHub ever returns it with different casing. I plan to revisit normalization when the skill needs to be split out into another repository.
That’s all from adding a hermes-talaria skill that approves user-review-requested:@me PRs in a single pass from a frozen oldest-first snapshot with a 👌 body, from the Gemba.