Skip to content

oliver-kriska/claude-elixir-phoenix / targets/dsh/skills/phx-watch-pr

phx-watch-pr

Verified

Watch an Elixir/Phoenix PR for new review comments (bot + human) and CI results via a background watcher that wakes Claude only on real events. Use after opening a PR or pushing, while waiting on CI or reviewers.

FileKindSize
SKILL.mdskill md7.5 KB
references/watcher-mechanics.mdmarkdown6.7 KB
scripts/watch-pr.shexecutablescript9.8 KB

references/watcher-mechanics.md

View on GitHub
# Watcher Mechanics — Why Background Events Beat Polling

## The cost problem with hand-rolled loops

A foreground `while true; sleep 120; gh api ...` loop is the worst design
on both axes:

1. **Context burn** — every poll's `gh` JSON lands in the transcript.
   30 polls × full dumps = tens of KB of context for "nothing changed yet."
2. **Cache burn** — between-turn waits longer than the prompt-cache TTL
   (5 min default) force a full uncached context reload on the next turn:
   the ~35–55K-token prefix re-writes at 1.25×–2× instead of re-reading
   at 0.1×. A 300s interval lands exactly on the eviction boundary — the
   single worst choice. Under ~270s keeps the cache warm; anything longer
   should commit to 1200s+ so the reload price is paid once, not per poll.

The cheapest design pays the reload price ZERO times while idle: Claude
takes no turns at all between events. The script polls in its own process;
Claude's context is untouched until a real event arrives.

## Mechanism comparison

| Mechanism | Idle token cost | Notes |
|-----------|----------------|-------|
| Foreground bash loop | Worst — every poll in context | Reject |
| **Monitor tool** (v2.1.98+) | ≈0 — streams filtered event lines | **Preferred.** Purpose-built: background script, each stdout line returns as an event. Capped at 30 min per watch since v2.1.271 — the script re-arms via `rearm` segments. Not available on Bedrock/Vertex/Foundry |
| Bash `run_in_background` | ≈0 — Claude re-invoked when the script exits | Portable fallback; one shot per launch (exit-on-first-terminal-event) |
| `/loop` + ScheduleWakeup | One full turn per wake (context reload each time) | Fallback only; clamped to [60s, 3600s]; Anthropic's own docs note dynamic /loop may switch to Monitor because it's cheaper |

Anthropic's scheduled-tasks doc states this directly: Monitor "avoids
polling altogether and is often more token-efficient and responsive than
re-running a prompt on an interval."

## Watcher contract (what watch-pr.sh implements)

- **Inputs**: PR number, dimensions (`reviews,comments,checks`), env
  overrides `WATCH_INTERVAL` (default 30s), `WATCH_MAX_DURATION` (3600s),
  `WATCH_SEGMENT` (default = max duration), `WATCH_RESUME`,
  `WATCH_BASELINE_TS`, `WATCH_DELTA_FILE`
- **One `gh pr view --json` per cycle** covers state, reviews, comments,
  and checks — cheaper than four REST calls, and the JSON never reaches
  Claude's context
- **Events**: one stdout line + one JSONL row in
  `.claude/watch/pr-{n}.jsonl` per genuinely-new item (dedup via seen-ID
  tracking, baseline timestamp filters out pre-existing reviews)
- **Terminal lines (silence ≠ success)**: `merged`, `pr_closed`,
  `watchdog` (max duration), `watch_error` (5 consecutive gh failures —
  don't loop forever on a dead token)
- **Segments (CC 2.1.271+)**: Monitor watches end within 30 min (10 in
  `-p` runs) and the old no-timeout `persistent` option is gone. After
  `WATCH_SEGMENT` seconds the script emits a non-terminal `rearm` line
  carrying `baseline`, `started` and the last check state, then exits 0.
  Restarting with `WATCH_RESUME=1` reads that line back from the delta
  file and seeds seen review/comment ids (events carry `id`) and codex
  flags from this watch's rows, so nothing is re-reported or dropped.
  `WATCH_MAX_DURATION` still bounds the whole watch across segments

## Codex mode (`--codex`)

Verified against the ChatGPT Codex GitHub connector (2026-07-03,
reaction landing spots re-verified live 2026-07-10):

- **Trigger**: PR going ready auto-registers a review (codex reacts 👀 on
  the PR BODY — no comment needed), or comment `@codex review`. Pushing
  commits does NOT re-trigger — rounds after the first need a fresh
  trigger comment. The skill's preflight checks the PR body's bot
  reactions since the head commit and SKIPS posting when a review is
  already in flight (👀) or already clean (👍).
- **Signals**: 👀 reaction = codex acknowledged and is reviewing;
  👍 reaction = clean pass. A clean pass can ALSO arrive as a bot
  COMMENT — `Codex Review: Didn't find any major issues` with
  `Reviewed commit: {sha}` (confirmed live on a comment-triggered
  round); the watcher classifies it as `codex_clean`, and other bot
  comments containing "Codex Review" as `codex_review`. Auto-triggered
  reviews react on the PR body (confirmed live); comment-triggered
  rounds react on the trigger comment — the watcher polls both, with
  PR-level reactions time-filtered by `WATCH_CODEX_SINCE` so stale
  👀/👍 from earlier rounds or pushes can't fire spurious events.
- **Freshness anchor**: the `Reviewed commit: {sha}` marker beats every
  timestamp comparison — commit committer dates are client-set and skew
  (observed live: a clean comment predating its reviewed commit's
  committer date by 9 minutes). Compare shas when available; use
  reaction timestamps only as the in-flight heuristic.
- **Review arrival**: a PR review headed `### 💡 Codex Review` with
  `Reviewed commit: <sha>` — detected via body marker, not bot login
  (login differs per endpoint: `chatgpt-codex-connector[bot]` vs Bot type).
- **Latency**: 14–18 min per round on large PRs → `--codex` raises
  MAX_DURATION to 7200s. `codex_timeout` fires if no 👀 within 300s
  (`CODEX_ACK_TIMEOUT`) — the repo probably lacks the connector; the watch
  continues as a plain watch.
- **Round bookkeeping lives in the skill, not the script**: one watcher
  per round. After fixes are pushed, the skill posts a new `@codex review`,
  captures the new comment id, and restarts the watcher with
  `WATCH_CODEX_TRIGGER_ID=<new id>`. Rounds are capped (default 3) —
  each round consumes Codex cloud quota.
- **Env contract**: `WATCH_CODEX=1`; `WATCH_CODEX_TRIGGER_ID` (empty =
  auto-registered mode: PR-level reactions only); `WATCH_CODEX_SINCE`
  (ISO-8601 floor for PR-level reactions — head-commit time in
  auto-registered mode, defaults to watcher baseline otherwise);
  `CODEX_ACK_TIMEOUT` (default 300). At most two extra REST calls per
  30s tick (~240 req/hr) — still trivial against the 5,000/hr budget.

## Rate limits

30s cadence on a single PR is trivially within the 5,000 req/hr
authenticated budget. For multi-PR watching, the REST comments endpoint
supports conditional requests (`curl --etag-save/--etag-compare`) where
304 responses cost zero rate-limit points — GraphQL (`gh pr view`) does
not support ETags. Deferred until actually needed.

## CI-only watching

`gh pr checks {n} --watch --fail-fast --interval 10` already blocks until
all checks finish and exits with `0` = pass, `1` = fail, `8` = pending.
For "I just pushed, tell me when CI is green/red" there is nothing to
build — wrap it in `run_in_background` and the exit IS the signal.
`gh run watch {run-id}` is the equivalent for a single Actions run.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall