cross-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# cross-review — independent verification

The implementer never signs off on its own work — a different model does, and
review is a sub-agent that returns a structured report, not a transcript
anyone needs to read through.

Cross-review runs LOCALLY, BEFORE the PR is created (config.yaml's
Cross-Review Rule, layer 1). The implementer resolves every blocking
finding first; only a clean review earns the PR. CodeRabbit then reviews
the PR independently after creation (layer 2 — never pre-empted or
duplicated here), and pr-shepherd owns everything after PR creation
(layer 3).

## Procedure
1. Verify the worktree is fully committed BEFORE taking the diff:
   `sys_os_shell("git -C .worktrees/<task_id> status --porcelain")` must
   return EMPTY. Staged, unstaged, or untracked files mean the branch diff
   would miss work — send the task back to the implementer to commit
   everything first; never review a dirty worktree. Then get the diff —
   `sys_os_shell("git -C .worktrees/<task_id> diff main...HEAD")`. (Only
   for a PR that already exists — e.g. re-reviewing a fix pushed to an
   open PR under pr-shepherd — use `gh pr diff <pr>` instead.)
2. Run the deterministic gates first — tests / lint / typecheck via
   `sys_os_shell`, executed FROM the task's worktree (e.g.
   `sys_os_shell("cd .worktrees/<task_id> && <test cmd>")`) so they
   validate the diff under review, never buhhdy's own checkout — gates run
   anywhere else are false-green evidence. If red, re-dispatch the
   implementer to drive it green first; don't involve the reviewer yet.
3. Dispatch a DIFFERENT-vendor sub-agent as reviewer (Claude built it →
   `codex`, `gemini-*`, or `opencode`; Codex built it → `claude_code`,
   `gemini-*`, or `opencode`; a `gemini-*` worker built it → `claude_code`,
   `codex`, or `opencode`; opencode built it → `claude_code`, `codex`, or
   `gemini-*`. The three `gemini-*` workers are ONE vendor and never review
   each other; `gemini-*` defaults to gemini-standard, or gemini-complex
   for large/multimodal diffs). Use a task-based title such as
   `review-auth-refactor`, never the raw vendor name:
   `sys_session_send(agent="claude_code"|"codex"|"gemini-standard"|"gemini-complex"|"opencode", title="review-<task_slug>",
   args={purpose: "review", input: "<the diff> + <the acceptance contract>.
   Review ONLY against the contract. Report blocking / non-blocking /
   suggestions. Do not edit code."})`. Give it the diff as text — do NOT point
   it at the implementer's worktree. Fetch the diff and emit the
   `sys_session_send` call in the SAME turn you decide to review — never end a
   turn having only announced "I'll load cross-review and fetch the diff" with
   no tool call (that dropped turn stalls the run; nothing dispatches and no
   inbox wake arrives). Once the reviewer dispatch is in flight, end your turn;
   collect the inbox-delivered structured report with `sys_read_inbox` when it
   returns. Use `sys_session_get_history` only to debug an empty or unclear
   review result.
4. The reviewer SURFACES issues; it does not fix them.
5. For each **blocking** issue: add a fix-task to the registry scoped to the
   same worktree, and send the concrete fixes back to the SAME implementer
   conversation via `sys_session_send` — reuse the original implementer's
   `agent` + `title` (or address it by `session_id`) with
   `purpose: "implement"`, so the worker keeps its worktree/branch context.
   A new title would spawn a fresh worker with no memory of the task. Then
   loop to step 1.
6. When gates are green AND there are zero blocking issues, the diff passes
   review — NOW the implementer opens its PR (body carrying `Closes #N`
   for its tracker issue and the test-run evidence from step 2: commands
   run + results; verify both are present before counting it deliverable).
   Record the PR URL in the registry and hand the PR to pr-shepherd.
   buhhdy does NOT merge it.
7. If the contract can't be satisfied within the escalation rule's budget
   (two fix attempts by the original implementer — see core-workflows'
   shared notes), stop and escalate to the human with specifics, and WAIT.

## Notes
- Cross-review requires a reviewer from a DIFFERENT vendor than the implementer,
  so it needs at least two AVAILABLE workers (per buhhdy's roster preflight). If
  only one worker — or only one vendor that can review this implementer's PR —
  is available on the machine, you CANNOT run independent cross-vendor review:
  don't dispatch a reviewer that can't boot, say so explicitly, and pull in the
  human at the plan gate.
- Give the reviewer ONLY the diff + contract — never the implementer's
  transcript or worktree. The cross-vendor independence is the whole point.
- Review is a coding sub-agent (`claude_code`/`codex`/`gemini-*`/`opencode`) dispatched with
  `purpose: "review"` — a DIFFERENT vendor from the one that built the diff. It
  reports issues and never edits; only the implementer opens a PR, so a stray
  reviewer edit never reaches the deliverable.
- Non-blocking issues / suggestions go in the registry as follow-ups; they
  don't block the PR.

From uhstray-io/huhhb, MIT.

More from uhstray-io/huhhb