mgratzer/forge/forge-guard

Guard a Pull Request

Take an open PR from "pushed" to "the human can look now" without asking anything along the way.

Input

PR number or URL ($ARGUMENTS; auto-detects from the current branch if omitted). Optional: -- <additional context>, e.g. -- skip the security pass. --max-rounds <n> overrides the project setting.

The skill is unattended by nature: it decides on evidence, replies to feedback, and defers to Issues instead of asking.

Process

Step 1: Locate the PR and Read the Configuration

gh pr view $PR_ARG --json number,headRefName,baseRefName   # PR, BRANCH, BASE
ME=$(gh api user --jq .login)
[ "$(git branch --show-current)" = "$BRANCH" ] || gh pr checkout "$PR"   # every git command below assumes the PR branch

Read the project's ## Unattended Shipping section per unattended-config: peer reviewer, security-sensitive paths, max rounds. Report reviewing via status-reporting.

A push makes land's verdict stale: right after this run's first push, in whichever step, remove land's label once, per status-reporting with STATE empty. A refused removal goes under Open for the human.

Step 2: Run Quality Passes

Simplification pass — if the runtime provides a simplification skill (Claude Code: /simplify), invoke it on the branch diff. Otherwise follow review-delegation with the default checklist narrowed to items 3 and 5 of review-dimensions. Skip it under forge-ship --guard, whose Step 2 already covered it, and report skipped (forge-ship).

Security pass — run when the PR carries a security label or gh pr diff "$PR" --name-only matches a security-sensitive path. If the runtime provides a security review skill (Claude Code: /security-review), invoke it; otherwise follow review-delegation with the Security & Correctness deep pass.

Triage findings from both passes with forge-ship's unattended rule, then run the project quality gates once, commit, and push — one push, so CI and the peer reviewer see one revision.

Step 3: Wait for Signals

Report waiting. Request the peer review first so it overlaps the CI wait — bot reviewers review a PR once and stay silent afterwards unless asked, and Step 2 just pushed past their first look. Skip the request when nothing was pushed since the last one, when the latest push only merged the base, when no peer reviewer is configured, or once the run has a substitute review:

gh api -X POST "repos/{owner}/{repo}/pulls/$PR/requested_reviewers" -f "reviewers[]=<PEER_REVIEWER>"

Wait per pr-readiness: How to Wait, then CI, then Review Signal. A wait exiting, or an event from a runtime that watches the PR, sends you to Step 4, which reads the PR afresh. When the review signal falls back to a review from before the push, or rests on a partial review, note that in the summary.

Failed review — the review loop printed failed. Back off 5 minutes in the loop's 30-second steps (for _ in $(seq 1 10); do sleep 30; done: rate limits outlast a quick retry), set SINCE=$(date -u +%FT%TZ), request the peer reviewer once more, and run the loop again with that $SINCE, so the first failure no longer counts. Failed again or silent: run review-delegation's default pass on the branch diff as the substitute review, and post its findings in that comment. Step 4 handles its findings as it handles unaddressed feedback, and the substitute satisfies the signal for the rest of the run.

Step 4: Decide, then React

Check the terminal conditions first, on every round:

• `review-ready` — branch mergeable, no check pending on the head (none registered yet within 3 minutes of a push counts as pending), CI green apart from pre-existing failures, review signal satisfied, no unaddressed feedback or substitute review findings, nothing needing a human decision
• `needs-human` — anything that stops progress: a wait cap expires without its signal, the round limit is reached, a check the branch caused fails twice with the same error, a flaky or external check stays red, a conflict can't be resolved, a reviewer repeats an answered point, or only items needing a human decision remain

When neither applies, react in this order (mergeability, CI, feedback) and go back to Step 3. One trip is one round, however many pushes it makes, and rounds count across turns; a trip that only reruns a flaky check or finds checks still pending is not. Start each addressing detail with round <n>/<max>: this trip's number and the round limit. A trip that isn't a round repeats the last round's number, or round 0/<max> before the first.

Branch not mergeable — per pr-readiness. React to BEHIND once per run; after that, a branch that is only behind counts as mergeable and the summary says so. Report addressing, merge the base in, run the quality gates, commit, push:

git fetch origin "$BASE" && git merge --no-edit "origin/$BASE"   # merge, never rebase: the guard never force-pushes

Resolve a conflict only when both sides' intent is clear from the code and its history; otherwise git merge --abort and stop with needs-human, naming the files.

CI failed — report addressing, then sort each failed check per pr-readiness before touching anything:

• Pre-existing — leave it and name it in the summary.
• Flaky — rerun it with gh run rerun "$RUN" --failed && gh run watch "$RUN" --exit-status only while the run's attempt is 1 and nothing else in this trip pushes (a push starts a fresh run anyway); still red on a later attempt, leave it for the human.
• Caused — fix it, run the quality gates, commit, push.
• Not an Actions job — fix it only when its description and link point at the diff, otherwise leave it for the human with the reason.

Unaddressed feedback — what Open Feedback returns, apart from its No ask items and our standing "Needs your decision" replies — report addressing and run the forge-address-pr-feedback process with --unattended, reusing $PR and $ME. Items it reports as needing a human decision no longer block the wait, but they turn the outcome into needs-human. Substitute review findings have no threads: triage them with forge-ship's unattended rule, run the quality gates, commit, and push.

Never merge, never force-push, never close the PR. Report the terminal state via status-reporting, then summarize.

Step 5: After a Terminal State

A runtime that watches the PR keeps sending events after the run's terminal state, whether this skill or forge-land reported it. Check each one against the PR's current head:

• No-op — the PR is merged or closed, the event is about an older head, it is only about a comment or review that Open Feedback doesn't return or counts as No ask (a failed review, a bot's report), or the wake is a stopped wait exiting. Say so in one line and change nothing: no label, no ## Risk, no new report.
• Re-enter — anything else on the current head (a CI failure, a conflict, unaddressed feedback) goes to Step 4 with the rounds so far. The re-entry's first push removes land's label again (Step 1). Under forge-ship --guard, or when forge-land reported the last terminal state, reaching review-ready continues with its process, since a push makes its verdict stale. Ending in needs-human, pushed or not, removes land's label too, disables any auto-merge land armed (gh pr merge "$PR" --disable-auto), and says the ## Risk no longer holds. Report only the new terminal state, once, and summarize again.

Output Format

## Guard Summary
 
**PR:** #<number>: <title>
**Result:** review-ready | needs-human (<reason>)
**Rounds:** <n> of <max>
 
### Passes
- Simplify: applied <n> findings | skipped | skipped (forge-ship)
- Security: applied <n> findings | not triggered | skipped
 
### Rounds
1. Branch <mergeable | updated from base | conflicts resolved>, CI <green | failed → fixed | flaky → rerun green | pre-existing: <check>>, review <present (<login>) | partial (<login>: <the message>) | fell back to earlier review | substituted (<PEER_REVIEWER> failed: <reason>) | none configured>, threads <n addressed, m deferred>
 
### Open for the human
- <thread or comment url>: <the decision, with both options>
- Pre-existing: <check>, fails on <base> too
- Deferred: #<issue> (<title>)

Guidelines

• Evidence over questions — nothing in this skill asks the user; every judgment call is written into a reply or an Issue
• Bounded everything — rounds, waits, and polling intervals all have caps; a stuck guard ends in needs-human, not in a loop

Related Skills

Composed by: forge-ship --guard runs this process after its own review. Uses: forge-address-pr-feedback --unattended for each feedback round. After review-ready: Use forge-land to judge the PR's risk and write it into the PR.

Example Usage

/forge-guard
/forge-guard 123
/forge-guard 123 --max-rounds 2 -- treat performance comments as deferrable