PR shepherd — the loop's handoff + verification moves, applied to PRs

A loop has five moves: discovery → handoff → verification → persistence → scheduling
(see docs/20-loops.md). morning-triage is discovery — it finds
work. This skill is what happens after a PR exists: no PR sits red waiting for a human to
diagnose a check that a machine can read. It shepherds each open PR to exactly one of three
outcomes: merged (gate satisfied + authority granted), ready-to-merge (reported), or
inbox (needs a human, with the diagnosis already written).

Enumerate

gh pr list --state open --json number,title,author,isDraft,isCrossRepository,headRefName,statusCheckRollup

Skip drafts. Fail closed on forks: if isCrossRepository is true — or the field is
missing from the response — the PR is read-only: diagnose and comment, never check out into a
pushable worktree, never push.

Diagnose — read the check, don't guess

For each red check, read the actual failing step (gh run view <run-id> --log-failed) and
classify it. The class decides the action — this is the judgment step, don't skip it:

class	signature	action
environmental	missing secrets (Dependabot actor), runner flake, quota	note it; if it recurs, fix the workflow (root cause), not the PR
mechanical	drift/sync gates, lint, format, lockfile, generated files	fix it on the PR branch
real defect	failing tests on changed logic, security finding	never auto-fix silently — comment the diagnosis on the PR, mark inbox

A failure that pattern-matches "flake" still gets its log read once. Silence is not success:
a check that never ran (skipped, stuck queue) is a finding, not a pass.

Fix — mechanical only, verified before pushed

Work in a scratch worktree (git worktree add … origin/<branch>), never in the main checkout:

1. Make the smallest fix the failing gate names (e.g. the gate says
   run: cp sdlc/workflows/X .github/workflows/ — run that).
2. Run the same gate locally and watch it pass before pushing. Never push a guess.
3. Push to the PR branch with a commit message that names the gate it satisfies.
4. Three strikes: after 3 failed fix attempts on one PR, stop — mark it inbox with what
   was tried. A non-converging loop must stop spending
   (the resource-ceiling principle).

Gate — where the loop stops

Merge requires all of:

• every non-environmental check green (environmental reds are named in the report, not ignored);
• the human granted merge authority in the current session ("validate and merge",
  "/pr-shepherd --merge"). Authority is per-session, never assumed from a past one;
• squash merge, never force-push, never merge red, never bypass a required check.

Without authority: report the PR as ready-to-merge with a one-line verdict per check.
The merge button is the human's; the shepherd's job is to make pressing it trivial.

Persist

Append one row per touched PR to state/shepherd.md (create if absent) so the next run
resumes instead of re-diagnosing. The agent forgets; the repo does not.

| pr | class | action | status |
|---|---|---|---|
| #71 | mechanical (mirror drift) | synced templates, pushed | merged |
| #74 | real defect (auth test) | diagnosis commented | inbox |

Schedule

• On demand: /pr-shepherd.
• Interval (session open): /loop 15m /pr-shepherd — each firing re-reads state, handles
  what changed.
• Unattended cadence (no session open): compass schedule add pr-shepherd --twice-daily
  — a bounded headless run (turn + budget + timeout capped, spend ledgered) at 09:07 and
  17:07 while the laptop is awake, with merge authority and the same rails
  (sdlc/routines/prompts/pr-shepherd.md). Crontab skips missed slots; it doesn't catch up.
• Every firing re-reads state/shepherd.md first; a PR already inbox stays with the human
  until they act — don't re-litigate it every run.