babysit-pr-local

Files (2)

• SKILL.md
• canonical-wiring.md · recipes/

SKILL.md (first lines)

> [← Skills index](../../README.md)

# /dev-kit:babysit-pr-local — local-mode PR babysitter

## What it does

Monitors the current branch's PR and iteratively resolves every
blocker using a **local LLM judge** (`bin/review-local.sh`) instead of
GH-Actions, until the PR reaches local verdict = `Approve` and the
deterministic CI checks (`branch-policy`, `secret-scan`, `validate`)
pass. Each iteration is evidence-driven (MUST-L3): the skill quotes
the local audit comment + pytest tail line + combined-verdict line
before claiming a step is done.

Local-mode sibling of `/dev-kit:babysit-pr` (which still drives
iteration via GH-Actions). Both share `lib/babysit_pr_cli` helpers,
the lock protocol, and the worktree-detect plumbing; the algorithm
differs in five steps (see §Algorithm). Operators do not pass flags:
the local judge replaces CI's `review`/`security`/`maintenance` jobs
and the pre-push pytest gate is always on. `gh pr merge` is always a
human action — auto-merge is never invoked.

---

## Inputs (resolved at runtime, NOT user args)

| Variable         | Source                                                                 |
|------------------|------------------------------------------------------------------------|
| `PR_NUMBER`      | `gh pr view --json number` for the current branch                     |
| `PR_STATE`       | `gh pr view --json state` (`OPEN` required to proceed)                 |
| `REVIEW_VERDICT` | Local audit comment verdict from `bin/review-local.sh` (via exit code + `<!-- dev-kit-verdict-audit -->` line) |
| `CHECKS`         | `gh pr checks --json name,state,conclusion` (deterministic CI checks only) |
| `BRANCH`         | `git rev-parse --abbrev-ref HEAD`                                      |
| `MAX_ITERS`      | `1000` (matches `/dev-kit:babysit-pr`; the 3-consecutive-no-progress guard still triggers earlier) |
| `OPERATOR_HANDLE`| `gh api /user -q .login`                                               |
| `LOCAL_TEST_CMD` | `pytest -q` (the pre-push pytest gate default; MUST-L3 enforces the tail line) |

### Hidden flags (never appear in slash description)

The slash command is **0-arg** — operators run
`/dev-kit:babysit-pr-local` with no arguments. Three flags exist for
tests + the rare power-user override; all are suppressed from
`--help` and `argument-hint` so the operator never sees them.

| Flag | Effect | Why hidden |
|---|---|---|
| `--pr N` | Override current-branch PR discovery with explicit PR number | Tests + the rare case where the PR was opened from another worktree |
| `--local-test-cmd CMD` | Override the pre-push pytest gate default (`pytest -q`) | Non-pytest projects (Make, tox) need a real gate; defaulting to `pytest -q` would let a non-pytest project silently pass on `exit 0` with no pytest-tail line |
| `--local-mode` | Internal routing flag — already implied by the slash, kept so the parser doesn't double-route | Routes argv without double-parsing |

These are read by `lib/babysit_pr_cli.parse_babysit_args` (hidden via
`argparse.SUPPRESS`) and surfaced on the resulting Namespace as
`ns.pr`, `ns.local_test_cmd`, `ns.local_mode`. The pre-scan reader is
`lib/babysit_pr_cli.is_local_mode(argv)` for callers that need to
route before invoking the full parser.

If `--pr N` is absent and `PR_NUMBER` is empty, print a one-line
message and exit 1 explaining that an explicit `--pr N` or
current-branch PR is required. If the resolved `PR_STATE != OPEN`,
print a one-line message and exit 1. Never create a PR implicitly.

---

## Worktree-aware execution

The skill MUST run inside the worktree that owns the PR's branch —
edits from the main checkout are denied by `worktree-guard`. The
parent detects the session cwd via `hooks/lib/worktree-detect.sh`
and either runs in place or spawns a sub-agent in the resolved
worktree.

The lock file lives at `<worktree_path>/.dev-kit/babysit.lock`. It is
**shared** with `/dev-kit:babysit-pr` (same path) — if both skills
race on the same worktree, the second arrival sees a fresh lock and
refuses with `already running`. The
`lib/babysit_pr_reliability.is_stale_lock` helper handles SIGKILL /
OOM via the same 30-minute TTL. The lock body appends
`source=babysit-pr-local` so a post-mortem can tell which skill held
the lock; the parent skill writes the same prefix without `source=`.

Sub-agent delegation + parent-side preflight live in
[`recipes/canonical-wiring.md`](recipes/canonical-wiring.md).

---

## Algorithm

### MUST — re-verify state immediately before acting

Every read of `gh pr view`, `gh pr checks`, `gh run view`, `gh api`,
or any other PR / workflow / status query is **racy**. The PR state,
check rollup, review verdict, and individual check conclusions can
change at any moment because of:

- a maintainer pushing / force-pushing a commit (fires ` `pull_request` `
  → re-runs workflows → updates check conclusions)
- another operator running `gh workflow run ...` to dispatch workflows
- a queued workflow run starting or completing
- the local `bin/review-local.sh` itself finishing and posting a fresh
  audit comment mid-iteration

The local babysitter MUST re-query the relevant state — REVIEW_VERDICT
(read from the latest audit comment), CHECKS, the PR headRefOid, the
operator handle, anything else the next decision depends on — **immediately
before acting on it**. A value read at the start of an iteration or at
the top of a Claude turn MUST NOT be reused as "the current state"
several turns later; the operator or another automation may have changed
it in between.

Failure modes this rule prevents:

- claiming a PR is "approved" because the most recent local verdict was
  "Approve" at the start of the turn, after a re-run posted a fresh
  verdict that's actually "Changes Requested"
- diagnosing the wrong failing-check because a fresh `pull_request` run
  re-rendered the rollup with a different `databaseId` than the cached one
- running `gh run watch $REVIEW_RUN` against a stale run id because the
  run was force-cancelled and replaced while the babysitter was drafting
- missing a fresh linear-pr-sync SUCCESS that replaced a stale FAILURE
  entry in the rollup

From sh-ai-x/dev-harness-kit, MIT.

More from sh-ai-x/dev-harness-kit