external pr review

Engineering Community

Skill notes

Calibrating findings

A finding is blocking only when merging the diff as-is would cause something observable to break or regress: Real bug introduced by the diff (wrong condition, off-by-one, missing await). Security regression introduced by the diff. Missing/broken tests for behavior the diff explicitly changes. Obvious perf regression (N+1 on a hot path, sync I/O in async hot loop).

Arguments

<pr> (required): full URL https://github.com/owner/repo/pull/N, or bare #N / N when invoked from inside a clone of that repo. --backend: codex (default), cursor, or gemini. --model: backend-specific override. --effort: codex-only. low / medium (default) / high. medium catches cross-call-site coverage gaps that low misses; high for genuinely subtle correctness.

Step 1: Resolve the PR

Closed/merged → ask before continuing. Draft → proceed, note in verdict.

Step 2: Check out the code

Need an isolated worktree at the head SHA. Try in order. Method A — worktree from local clone (when git config remote.origin.url matches $OWNER/$REPO): Method B — fresh shallow clone: gh pr checkout fails on shallow clones with cannot set up tracking information — the fallback works because the fetch already created the remote-tracking ref. If bramble later complains about missing base, git fetch --unshallow.

Step 3: Build the review goal

--goal is the highest-leverage knob. Without a tight goal, codex/cursor wander into infra/lockfile/cross-repo audits and burn 5–8 minutes on a small PR. Write this to $WORKTREE_DIR/.external-review-goal.txt: If the PR body is empty or one-liner, substitute title + first commit subject. Don't let the model invent intent from the branch name.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Resolve the PR

Closed/merged → ask before continuing. Draft → proceed, note in verdict.

02
Step 2: Check out the code

Need an isolated worktree at the head SHA. Try in order. Method A — worktree from local clone (when `git config remote.origin.url` matches `$OWNER/$REPO`): Method B — fresh shallow clone: `gh pr checkout` fails on shallow clones with `cannot set up tracking information` — the fallback works because the fetch already created the remote-tracking ref. If bramble later complains about missing base, `git fetch --unshallow`.

03
Step 3: Build the review goal

`--goal` is the highest-leverage knob. Without a tight goal, codex/cursor wander into infra/lockfile/cross-repo audits and burn 5–8 minutes on a small PR. Write this to `$WORKTREE_DIR/.external-review-goal.txt`: If the PR body is empty or one-liner, substitute title + first commit subject. Don't let the model invent intent from the branch name.

04
Step 4: Run bramble code-review

Run it under `Monitor` (typical 2–6 min): Do not also call `ScheduleWakeup` or any sleep loop while waiting. Monitor's completion event is the only signal needed. `ScheduleWakeup` with a slash-command prompt will re-fire the whole skill and double-post the review. If the envelope reports `status: "error"` but `review.raw_text` contains a fenced ```json``` block, recover by extracting the inner JSON. Otherwise report stderr path and stop.

05
Step 5: Triage

Each envelope finding has a `severity` (`high`/`medium`/`low`/`nit`), `path`/`line`, and `description`. For each: Apply the blocking test from "Approval bias" above. Cross-reference the cited file:line. If it isn't in the diff, demote to optional (pre-existing) or drop (stale). Disagree with the model's severity when warranted — a `high` style nit is optional; a `low` real bug is blocking.

06
Step 6: Print the verdict

Verdict: ≥1 blocking → REQUEST CHANGES. ≥1 substantive optional (real non-blocking bug, missed migration site, likely-unintended behavior) → APPROVE with suggestions. Otherwise → APPROVE. If only pure nits remain, list them under a "Nits (take or leave)" footer and keep the headline plain APPROVE.

07
Step 7: Ask before posting

First, idempotency check — has the current user already reviewed this SHA? If yes (likely a re-fire), offer *Update existing*, *Post anyway*, *Skip* — default Skip. Otherwise ask via `AskUserQuestion`: Approve on GitHub (only when verdict is APPROVE or APPROVE-with-suggestions): `gh pr review --approve --body-file <file>`. Comment only: `gh pr review --comment --body-file <file>`.

08
Step 8: Cleanup

Worktree → `git worktree remove --force <path>` then `git update-ref -d refs/remotes/origin/pr-<N>`. Temp clone → `rm -rf <path>`. Keep `$ENVELOPE` and `$LOG_DIR` on cleanup failure and tell the user where they are.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.