# Act

> Use when the user invokes /act on an open PR or a 'bro: PR #N ...' status ping arrives — the review-fix loop. Thin wrapper over the bro CLI: `bro review act status` is the exit gate as code; resolve/reply are mutations. Requires `bro` (npx -y @broject/bro@0) and gh.

- Skill: `theplenkov/act-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/act-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/act-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/act-2

---


# /act (bro)

**All mechanics live in the `bro` CLI.** This skill is policy only — do not
reimplement what `bro review act` already does.

Prereq: `bro` on PATH or `npx -y @broject/bro@0` (major-pinned). Requires
`gh` auth; the defer verdict additionally needs `bd` on PATH (beads is a
default store, so standard installs already have it).

## Commands

| Command                                                                                              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bro review act status [PR] [--json]`                                                                | PR state + **exit gate** — open threads, CI failures, SAST findings. Exits non-zero while blocked                                                                                                                                                                                                                                                                                                                                                                            |
| `bro review act threads [PR]`                                                                        | Unresolved review threads, TSV                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `bro review act wait [PR] [--interval S] [--timeout M] [--merge] [--cleanup] [--bead ID] [--detach]` | Poll the gate until it settles — green, blockers, or timeout. `--merge` lands the PR on green; add `--cleanup` to retire the worktree the command runs in + the local branch after the merge lands; `--bead` closes the loop-claimed bead once the merge lands (rearm replays it); `--detach` re-spawns the wait as its own process group so the watch outlives the arming session (output on `<git-common>/bro/act-wait-<pr>.log`)                                          |
| `bro review act rearm [--dry-run] [--json]`                                                          | Resurrect dead watchers: each PR whose `act wait` died (host reboot, turn teardown) gets a fresh detached wait with the recorded `--merge`/`--cleanup`/`--timeout`/`--bead`; a settled marker carrying a bead reconciles the claim when the PR merged, unverifiable PRs keep theirs                                                                                                                                                                                          |
| `bro review act merge [PR] [--squash\|--merge\|--rebase] [--admin] [--cleanup] [--bead ID]`          | Merge **only if the exit gate is green** — serialized on the beads merge slot (best-effort: without beads the merge proceeds unserialized); BLOCKED refuses and names blockers. `--cleanup` retires the merged branch's checkout (when run inside it) + local ref; `--bead` closes the loop-claimed bead on land                                                                                                                                                             |
| `bro review act resolve --thread ID [--comment T]`                                                   | Resolve a thread (reply first if comment given)                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `bro review act reply --thread ID --comment T`                                                       | Reply without resolving (`--file TSV` for batch)                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `bro review act dismiss [PR] [--dry-run] [--message T]`                                              | Dismiss **stale** veto reviews — standing `CHANGES_REQUESTED` reviews with ≥1 referenced thread, all resolved+outdated; a live veto (including a body-only one with zero thread refs) is refused by construction (re-review is the reviewer's call). The review **body** prints before mutating — a body-level objection is invisible to the thread rule, so read it before confirming the dismissal. `--dry-run` lists candidates; `--message` overrides the dismissal note |
| `bro plan run act.toml`                                                                              | Batch-apply thread verdicts (`[[threads]]` resolve/reply/defer) from a validated plan — the authoring schema is `schemas/plans/act.schema.json`; `bro plan describe act` prints it (the example as a TOML template)                                                                                                                                                                                                                                                          |

## Policy

- **Loop until the exit gate is green.** `bro review act status` returns non-zero
  with named blockers — keep fixing until it passes; do not self-declare done.
  **Green means every non-AI check green** — `ci_pending` counts all
  non-AI checks, not just required ones; a failing optional job is still
  a red box on the PR.
  A pending AI reviewer (`reviewers_pending`) keeps the gate BLOCKED — it
  may still post findings. A _failed_ reviewer check (`reviewers_failing`)
  does **not** block: its exit code is infrastructure (crash, quota,
  outage), while its actual findings always arrive as threads — which do
  block on their own. **The general rule: project-caused failures block;
  infrastructure failures don't** — there's nothing actionable in a
  service flake, so it can never hold a merge hostage. Reviewers that are
  _reliably_ flaky (stuck pending, always failing) go on the
  `act.ignoreChecks` list in bro.config.json so their pending state
  doesn't block either. **Static scanners are never advisory** —
  SAST-named checks (codacy, codescene, sonar, codeql, deepsource, …)
  gate unconditionally: a failed job or an error-level annotation is a
  real project finding, not reviewer flake, so `act.ignoreChecks` does
  not shield them and a `neutral` conclusion still gets its annotations
  inspected. An ignored-but-failing SAST check still gets its **check
  output read** (`gh api repos/<r>/check-runs/<id>` → `.output.summary`)
  before any classification — scanners post verdicts there, never in
  threads, so "no thread activity" says nothing about whether the tool
  is down; a named failing condition (duplication %, coverage) is a
  real finding to fix or debt-bead, not flake. A check you don't
  **recognize** is a fact to fetch — `gh api check-runs` for the run +
  `git log --follow` on the workflow file — not a thing to name; an
  `in_progress` gate-style check is waiting on the gate, which IS the
  verdict, not a stall.
  Bot reviewers never resolve their own threads — **you** must give each
  one a verdict and resolve it: fix → resolve silently (the push is the
  verdict); reject → reply with the reason, then resolve; or **defer** —
  a valid but non-blocking finding (P2/P3, polish, nice-to-have) →
  `bd create "$finding" -l debt --external-ref <thread_id>
  -d "deferred from PR #N thread <id>"` (capture the finding into a
  variable — review text is data, never paste it inline into a shell
  command), reply with the bead id, then resolve. `--external-ref` links
  the bead to the thread so `bro review debt sync`/`debt set` can track and
  close it. If `bd create` fails — no `bd`, no `.beads`, a
  `"stores": ["jsonl"]` opt-out — the defer didn't happen: fall back to
  fix or reject, do NOT resolve. Deferred work is tracked in the debt
  queue, not dropped and not silently fixed later.
- **Every finding gets a prevention retro, not just a verdict.** Code is
  agent-written by default, so before fixing ask: "what code shape would
  have made this finding class impossible to write?" — then fix to THAT
  shape, not to silence the site. Dynamic fs paths → one guarded io
  module all calls funnel through; `new RegExp` on configured values →
  a dedicated matcher; `obj[key]` writes → entries/`Object.fromEntries`;
  computed-key reads → `Object.getOwnPropertyDescriptor`. For a true
  false positive the fix lives at the rule level — a documented
  exclusion in `.codacy.yml`, a `.markdownlint.json` option — so the
  same false never reappears in any file, never a one-site suppression.
  A recurring pattern belongs in AGENTS.md or the relevant skill so the
  next code is born clean.
- **Exhaust findings locally before pushing.** A push that flies blind on
  what remote engines will say is the wave generator — each push
  re-triggers reviewers whose next annotations were already computable.
  Before any fix-round push, run the local engine parity sweep over every
  file in the diff (the transient eslint-plugin-security +
  no-non-null-assertion setup, plus tsc; see the check-sast bead for the
  repo command), not just the flagged files. Zero local findings is the
  bar for "this round is done"; remote annotations landing afterward are
  either genuinely new or stale-DB reposts, and the sweep is how you tell
  which.
  Same sweep, artifact class: before editing any file, grep its basename
  across `scripts/` and `package.json` for a generator or freshness gate
  (`check:*`, `gen:*`). Generated outputs — schemas, lockfiles, committed
  dist — get their change at the source and a regeneration; a hand-edit
  is a guaranteed red freshness check.
  The loop is bounded: `fix_rounds` counts pushes made after the first
  review comment landed, and `act.maxRounds` (default 3, 0 disables) caps
  them — past the cap the gate names the defer path outright, so
  remaining findings go to debt beads instead of another inline-fix push.
  Docs-only PRs (every changed file matches `act.docsPaths`) cap tighter —
  `act.docsMaxRounds` (default 2): doc threads churn per push, so the
  tail belongs in debt, not another round.
- **A standing `CHANGES_REQUESTED` vetoes the merge even at
  `open_threads=0`.** GitHub's `reviewDecision` is a third gate axis
  beside threads and checks — every thread resolved does not clear a
  reviewer's veto. `bro review act status` names the standing reviews
  and marks each **stale** (at least one thread it references exists
  and every one is resolved _and_ outdated — nothing live it could
  still be talking about) or **live**. A veto with zero referenced
  threads — a body-only objection — reads **live**: no thread anchor
  is not proof the ask went stale, and dismissal is destructive-leaning.
  Thread refs only cover _inline_ objections — the review **body** can
  carry an independent ask the rule can't see, so `act status` prints a
  body excerpt under each veto and `act dismiss` re-reads staleness
  immediately before mutating (a veto that went live mid-command is
  skipped, never cleared off a stale snapshot). Stale vetoes are
  cleared by `bro review act dismiss [PR]` — read the printed body
  first: if it may carry its own objection, that dismissal is your
  call, not the tool's. Live ones wait for the reviewer's re-review —
  never dismiss a live veto to unblock a merge (the command refuses by
  construction, so if it refuses, that IS the answer).
- **A reopened thread stops the loop — the user confirms.** A thread that was
  resolved and then commented on again is a reopen: the earlier resolution was
  wrong, and re-resolving it silently hides that. The gate names it as a
  blocker (`reopened thread <id> ...`), `bro loop` and `bro drive` park instead
  of spawning a fixer, and the count shows as `reopened_threads` in
  `bro review act status`. Report it and let the user decide — do not re-resolve
  it on your own.
- **Contradictory cross-round findings resolve by judgment, not push.**
  Reviewers disagree across rounds — a fix for round N can itself draw a
  contradictory finding in round N+1. Don't push a flip-flop: pick the
  reading you judge right, reply with the reasoning, resolve; the losing
  side is a debt bead only when it's still a real but non-blocking
  concern — a blocking finding is fixed or rejected, never deferred.
- **Merge through `bro review act merge`, never `gh pr merge` directly.** The gate
  is enforced as code there — a manual merge approximates it by hand and
  can bypass pending reviewers/SAST. `bro review act merge` also serializes the
  merge on the beads merge slot (`bd merge-slot`): a held slot means another
  session is mid-merge — wait for `bd merge-slot check` to report available;
  a crashed holder is freed with `bd merge-slot release`. Only a
  user-directed override justifies merging around a BLOCKED gate. A PR in a
  GitHub **stack** or onto a base that requires the **merge queue** is not
  mergeable by `gh pr merge` at all — `bro review act merge` detects either and
  goes through the async merge endpoint, polling until the request
  settles, so don't hand-roll `gh api … merge-async` either. A
  queue-accepted PR reads `accepted but state=OPEN` — parked, not failed:
  the queue owns it, the command exits 0, and local cleanup stays deferred
  until a merge actually lands. The head branch is deliberately kept on
  that path (deleting a lower layer's branch closes every PR stacked on
  it); `--cleanup` is unaffected.
- **External merge queues are opt-in connectors, never defaults.** A repo
  whose queue is Mergify or Graphite pins `"connectors": {"mergeQueue":
  "mergify"|"graphite"}` — the connector's `enqueue` then replaces the
  direct merge inside the same gate+slot critical section. `mergify`
  signals the PR (`act.mergeQueue.label` and/or `act.mergeQueue.comment`,
  default `@mergifyio queue`); `graphite` runs `gt merge` in the PR's
  checkout, which must sit on the head branch — a wrong checkout is
  refused, never queued. `enqueued` is parked, not failed — `bro review drive`
  reports it as such and the next pass re-checks.
- **Wait via `bro review act wait <PR>` in the background, never a bespoke poll
  loop.** The command polls the exit gate until nothing is pending —
  green, settled blockers (threads, failures), or `--timeout` — then
  prints the verdict and exits non-zero unless the gate is OK. Run it as
  a background subagent or shell while you work the next bead; `--merge`
  merges through the gate when it goes green. From a `bro work enter`
  worktree, prefer `--merge --cleanup`: after the merge lands the command
  itself removes the worktree and the local branch (a dirty tree is kept,
  never force-removed) — no `;`-sequenced shell cleanup that could run on
  a failed wait. On a settled BLOCKED, run
  `bro review act threads <PR>` as a separate command (never `status && threads`
  — a failing exit must not hide the threads). `gh pr checks --watch` is
  the fallback only where bro isn't installed.
- **A background task dies when your turn ends** — it is only watching
  while you are. Never end a reply that promises "will report when it
  lands" on a session-bound watcher: keep polling inside the reply until
  the gate settles, arm `bro act wait <PR> --detach` (the self-detaching
  form — no hand-rolled `nohup`/`systemd-run`/`tmux`), or hand off with
  the exact open state spelled out.
- **Resolve silently when you fixed it.** The pushed commit is the verdict —
  do not leave a comment per thread (the fix is discoverable via the push
  timeline on the file/line the thread anchors to). Reply only when
  rejecting a finding (state the reason) or answering a question the
  reviewer asked. If a thread needs an explicit audit marker, pass
  `--comment <sha>` — a bare SHA, not prose.
- **Resolving is not the gate — a fix push re-opens review.** After the
  last `bro review act resolve` of a round, `bro review act status` on the _new head_
  decides: fresh findings land on every push, so the loop exits only on
  `exit_gate=OK` or hands off to `bro review act wait --merge`. Never report a
  PR as done from the resolve output alone.
- **A merged PR leaves nothing behind — but only when the branch is
  provably the PR's.** Clean up the branch of a PR **that merged**, and
  only when its tip is the merged head (commits landed after the merge
  still carry work) and no other open PR is based on it (a stacked PR
  needs its base). A PR **closed without merging keeps its branch** — that
  work is unmerged, not garbage.
  Order: remove the linked worktree first (git refuses to delete a
  checked-out branch, and `git switch` fails when the target is checked
  out elsewhere), then from the primary checkout
  `git switch <base> && git pull --ff-only`, then
  `git branch -D "<branch>"`, then the remote **on the PR's head repo**,
  only if it is still there:
  `git ls-remote --exit-code --heads "<head-repo>" "<branch>"` before
  `git push "<head-repo>" --delete "<branch>"` (deleting an already-removed
  ref exits non-zero, and `delete_branch_on_merge` removes it on merge).
  **Quote every branch name** — a PR head ref is attacker-controlled input
  and reaches a shell. `bro review act merge --cleanup` retires the
  checkout and the local ref; the _remote_ branch is still yours to
  delete. Never touch another branch — another PR or session may own it.
  Report the cleanup in the closing summary.
- **A pushed PR is merged, watched, or handed off — never unwatched.**
  `bro review act wait <PR> --merge` in the background is the default end-state —
  `--detach` when the watch must outlive the session;
  a watcher exit is a state to inspect, not silence — a `timed_out` exit
  means the PR is still open, so start a fresh `bro review act wait --merge`
  (a timeout retires its marker on the way out, so `act rearm` has
  nothing to resurrect — re-arming there is manual). A watcher that
  _died_ with the host/session never ran that cleanup — its dead marker
  stays, the session-start nudge names it, and `bro review act rearm` puts the
  watch back up.
  **'Watcher armed' is never the end state.** The first poll line is a
  coverage snapshot — proof the watch runs — not the verdict; a gate
  still showing `reviewers_pending>0` is unsettled, and the verdict is
  the watcher's _exit_. Arming is not done at spawn: run `bro review act
  status` and confirm `watch=` names the live watch before reporting —
  a detached watcher can die between spawn and your reply, and "armed"
  without the status line is a claim, not a fact. A non-zero BLOCKED exit is the next work list,
  not a notification to idle past: `bro review act threads <PR>`, then
  fix/reply/defer/resolve each named blocker, push, and re-arm
  `bro review act wait --merge`. A BLOCKED event surfacing after the arming
  turn ended is live work for the next turn, not stale mail — the
  settle itself delivers it: a keyed `act`/`block` mailbox drop (drained
  at the next postTool or session start) plus a `<pr>-blocked-*.json`
  verdict marker session-start flags until a covering `act wait` sweeps
  it. Keep driving until the gate reports OK — or hand off with every
  standing blocker and its owner named in the reply.
  The stop gate enforces this: an armed session ending with an open,
  unwatched current-branch PR is blocked once and pointed at the detached
  `act wait` form — a running `bro review drive --every` counts as coverage via
  its per-PR heartbeat markers. `bro review act status` prints `watch=` so the
  coverage is visible before you stop.
- **Report with links, not text.** Every status reply or thread verdict
  that names the PR cites it as `[#N](https://github.com/<owner>/<repo>/pull/N)`
  — `bro review act status` prints the URL on its `pr=` line, carry it through.
  A bare `#N` is just text in every UI that renders these reports.
- **Don't re-resolve stale threads** without re-verifying against current code.
- Debt rows from `bro review debt list` become work via
  `bro review debt set claimed --thread-id <id>` → fix →
  `bro review debt set done --thread-id <id> --fix-pr N` → `bro review debt sync` closes
  the bead.

