roborev-setup-review
Work with the user to design a review for their repository, then write the
roborev configuration and rubrics that run it. The material can be code or
anything else committed to Git: a legal brief, a contract, a research report, a
manual. Find out what the reviewer should catch and why, play it back, and
write files only after the user approves.
Usage
/roborev-setup-review [what the review is for]
Explicit invocation only
Invocation must be explicit: literal personal /roborev-setup-review, or structured
Grok Build skill selection.
Requests such as “set up a legal review for this repository” without one of
these explicit mechanisms must use native behavior and must not run roborev.
Honor existing session authorization and project AGENTS.md instructions. This
invocation authorizes read-only inspection and the conversation. Writing
repository files, changing global configuration, installing hooks, committing,
and running a review each still need the user's approval.
Sandbox access
roborev uses a local daemon. If a command fails with permission denied, the
sandbox may be blocking its loopback port or Unix socket. Retry the same command
with the runtime's supported sandbox escalation mechanism when supported and authorized.
Do not start or restart the daemon because a sandboxed status probe cannot reach
it.
Look first
Before your first message, inspect what already exists. These checks are
read-only and need no approval:
roborev doctor --from-skill --json
roborev config --from-skill validate
roborev config --from-skill list --show-origin
roborev config --from-skill get sync.enabled
git config --show-origin --get core.hooksPath
Doctor reports which agents are installed, which agent runs reviews here, and
whether the Git hooks are installed. core.hooksPath shows whether the
repository's hooks come from somewhere else. Also read .roborev.toml,
REVIEW.md, existing rubric files, .kata.toml, and agent instruction files
such as AGENTS.md. A .kata.toml means the repository tracks its work in Kata.
List the layout, file types, headings, and recent commit subjects. Reading the
material itself, or comparing drafts against sources, is recon that the user
approves first.
Use what you find to skip questions you can answer. Do not recite it.
What do you already know?
- Everything that matters is in the request, such as "check every quote in
drafts/ against the exhibit text in exhibits/, on each commit". Skip the
conversation and go to Propose and get approval.
- A change to an existing review, such as one rubric or the batch size.
Ask only what the change needs, describe it in chat, and get approval.
- A new review with open questions. Start the conversation.
Your first message
Your first message has two parts:
- One line saying that if they would rather skip the questions, you can propose
a setup from what you found. If they take that offer, state your defaults in
plain words and go to the proposal. They still approve it before you write.
- One open question that gets them describing a concrete moment, such as "What
is in these drafts, and what is the mistake you most want caught before one
goes out?"
That's the whole message.
The conversation
End each message with one question, without a list of example answers. Use the
user's words. Say "reviewer", "check", and "source documents"; avoid
"subagent", "panel", and "custom review type" unless the user uses them first.
Get them describing before you offer options. Offer a short menu only when they
are stuck. When they say "just guess", propose something concrete and say it is
your guess. A guess they can correct ("I'm guessing the timeline file is the
source of truth for dates?") often beats a question.
Ground to cover. Treat this as territory, not a script:
- The material: what it is, who relies on it, and what happens when it is
wrong.
- The checks: what a careful human reviewer would check.
- Sources of truth: what each check compares against, such as files in the
repository, scans or PDFs, or an outside database. Reviewers read only the
repository and their prompt; see the rules.
- What to leave alone: findings they would reject on sight, house
conventions, and known non-issues.
- What fails: which mistakes must block and which are worth noting. Ask
with their own example: "Would a misspelled party name fail the review, or
just be noted?"
- When it runs: every commit, every few commits, on request, or on pull
requests.
- Who acts on findings: the user, a writing agent, or someone else, and
whether findings should also land in Kata when the repository uses it.
- Where the material may go: see Confidential material.
- Which agent runs it: the agent and model they already use and trust. Find
out which choices they want to make and which they hand to you.
Questions that work anchor in specifics: "Walk me through the last draft that
went out with a mistake." "If the reviewer could catch only one kind of mistake,
which one?" "What finding would make you roll your eyes?"
Once you have some grounding, offer recon: reading a few drafts and sources to
propose concrete checks. Say what you would look for. They decide.
Before proposing, consider several shapes privately: one reviewer with a
combined checklist, or several reviewers. Each reviewer is one more agent call.
Split checks only when they need different sources, a different agent, or a
different focus that one rubric would blur. Drop ideas that fight what the user
told you.
Play it back
As soon as you understand one part, describe it back in about 150 to 250 words,
then return to questions. Parts are usually:
- What the review is for and what it protects.
- Each reviewer: what it checks, against what, what it ignores, and what fails.
- When it runs and what happens to the findings.
Mark your guesses as guesses; only what they said goes in as theirs. End each
chunk by asking what is wrong or missing.
Turn answers into configuration
This mapping is for you, not the user. Use only what the conversation needs.
| They want |
Configure |
| One kind of check |
One [review.types.<name>] with a rubric template |
| Several checks |
One type per check, one [review.subagents.<name>] per type, and a [review.panels.<name>] listing them |
| Context every reviewer needs |
review_guidelines in .roborev.toml, or REVIEW.md |
| A source reviewers compare against |
Commit its text and name the path in the rubric |
| A short source every review needs in full |
[review.types.<name>.includes], rendered with {{ index .Includes "<key>" }} |
| One custom check after every commit or every N commits |
A type, a subagent that uses it, and a one-member panel; set hook_review_panel under [review]. Automatic reviews use this panel and carry no review type. Set post_commit_batch_size = N for every N commits. |
| Several custom checks after every commit or every N commits |
A type and subagent per check, a panel listing those subagents, and hook_review_panel under [review]. Set post_commit_batch_size = N for every N commits. |
| Keep the usual code review after commits too |
Add a subagent with review_type = "default" to the hook panel |
| Combine bursts of automatic reviews across repositories |
Set post_commit_batch_size and/or post_commit_quiet_period = "5m" globally. Each repo can override either value. The count threshold or quiet period queues the accumulated range, whichever happens first. Values below 2 disable the count threshold; an empty quiet period or "0" disables the timer. Pushes flush pending commits. Daemon restarts cancel timers but preserve pending checkpoints for the next commit or push. |
| The whole branch each time |
post_commit_review = "branch" |
| Reviews on request |
[review] default_panel, or --type and --panel |
| Reviews on pull requests |
[ci] panel; see https://roborev.io/docs/advanced/subagent-review-panels/#ci-panels |
| Verify CI findings before posting |
[ci] check = true, off by default; Codex checks findings in a sandbox and keeps the original review if checking fails. Global [ci] check_model and check_reasoning select its model and effort. |
| PR reviews only after a draft is marked ready |
Ask whether draft PRs should be skipped. For the daemon poller, global [ci] skip_drafts = true in ~/.roborev/config.toml (default false; no repo override). Ready PRs become eligible next poll without a push, under normal throttle, quiet-hours, and dedup rules. Active reviews are not canceled. |
| Rewrite checked CI findings |
[ci] rewrite = true requires check = true. Two additional Codex calls use stored findings and escaped PR context, without checker output, in a fresh read-only clone; failure keeps the checked text. |
| Shorter synthesized GitHub daemon comments |
[ci] comment_max_findings caps structured findings; 0 (default) is unlimited. Stored reviews stay complete. |
| Silence on clean synthesized GitHub daemon reviews |
[ci] comment_when_clean = false; default true posts clean comments. Stored reviews stay unchanged. |
| Only serious findings fail |
review_min_severity, plus severity guidance in each rubric |
| Passing reviews close themselves |
auto_close_passing_reviews = true |
| Reviewers that see the task a commit is for, from Kata |
[kata_context] with mode = "current"; commits name their issue, such as Closes: kata#abc4 |
| Failed reviews and findings filed as Kata issues |
A [[hooks]] entry with event = "review.*" and type = "kata" |
| Reviewers that read changed PDFs, scans, or images |
binary_evidence = true on the type; see https://roborev.io/docs/advanced/custom-review-types/#binary-evidence |
| A reviewer that looks things up through an outside service |
A strict tools policy on the type that grants exact MCP tools; see https://roborev.io/docs/advanced/custom-review-types/#granting-mcp-tools |
| Files reviewers should skip |
exclude_patterns |
| Reviewers that skip the setup itself, for non-code material |
exclude_patterns = [".roborev.toml", "review-rubrics/"] |
| A particular agent or model |
agent, model, and reasoning in the repository, type, or subagent |
| A reviewer on trial |
non_voting = true on the subagent |
| A reviewer that may flake |
allow_failure = true and timeout on the subagent |
| A combined review that checks each finding against the material, or labels findings for whoever fixes them |
synthesis_instructions on the panel; see https://roborev.io/docs/advanced/subagent-review-panels/#synthesis-instructions |
| Automation supplies every reviewer’s prompt and settings without editing repository policy |
POST /api/panel/enqueue; optional hold_synthesis waits for POST /api/panel/synthesize. See https://roborev.io/docs/automation/manual-panel-synthesis/#supply-a-panel-through-the-api |
For a small panel that checks findings before keeping them, use the
precise panel recipe.
It keeps agreed findings unless disproved and requires code evidence for
single-reviewer or contradicted findings. Silence is not disagreement.
Rules that matter:
- Put the setup in the repository's
.roborev.toml. Use the global
~/.roborev/config.toml only when the user wants the same review in every
repository, and only with their approval.
- Custom types need an agent with JSON Schema output:
codex, claude-code,
pi, or grok. Pi also needs its pi-json-schema extension, which
validation and doctor do not check. Custom types do not inherit
review_agent. Their agent resolves from type-specific repository settings,
the repository's generic agent, type-specific global settings, then global
default_agent (or codex when none is set). Check the effective agent for
each custom reviewer before leaving agent unset. If it differs from the
reviewer the user wants, ask and set the supported agent on the type or
subagent. When the user restricts providers, see
Confidential material. Otherwise ask which
supported agent to use. Do not choose one for them.
review_min_severity applies to every reviewer. Align each rubric's
severity levels so what the user said must fail sits at or above that one
threshold. Findings below it still appear in the review; they just do not
fail it.
hook_review_panel replaces whatever ran after each commit before,
including the usual code review and any global hook_review_panel. For
code, ask whether the usual review should keep running, and if so add a
default member to the panel.
- Type names start with a lowercase letter, use lowercase letters, digits,
and hyphens, and are at most 64 characters. These names are reserved:
default, review, general, security, design, lookahead,
test-value, goal, fix, refine, and classify.
- Keep rubrics and sources outside the snapshot directory (
.roborev/ by
default). It is ignored by Git, and roborev init refuses to run while
tracked files sit under it. Use a committed directory such as
review-rubrics/.
- Reviewers see the diff, the rubric, and the guidelines, and read other files
in the checkout with read-only tools. They cannot fetch URLs. Commit the
text a check needs. If a source can be neither committed nor reached
through an MCP grant, tell the user the reviewer can check only what the
repository holds.
- For PDFs, scans, and images, set
binary_evidence = true on the type.
Reviews of a commit or range then get a saved copy of each binary file
those commits add or change. Files the commits do not touch are not
included, so for a source that stays unchanged, such as an exhibit that
later drafts cite, also commit an exported text copy beside it. Reviews of
uncommitted changes fail when the type sets binary_evidence.
exclude_patterns removes files from the evidence as well as the diff, so
never exclude binary files a reviewer must read.
- The reviewer opens each saved copy with its own tools, so match the agent to
the files. Claude Code and Grok read PDFs and images directly. Codex reads
images, but reads a PDF only by running a converter such as
pdftotext on
the machine that runs the review, and gets no text from a scanned PDF. For
PDF evidence, propose claude-code or grok on the type, or check that the
converter is installed. Before relying on Pi, have the user confirm it can
read the file types involved.
- A reviewer reaches an outside service only through exact MCP grants on a
strict type: a
[review.types.<name>.tools] table with
mode = "read-only" and an mcp table that names each server and its
tools. Strict types run only on Claude Code, so set agent = "claude-code"
on the type. A backup agent that cannot enforce the policy fails the review
instead of running it. The global ~/.roborev/config.toml must define the
server in review_mcp_config and list each server/tool pair in
review_mcp_allowed_tools; repository config cannot set either. Propose
those global lines separately and write them only with the user's
approval. See
https://roborev.io/docs/configuration/#strict-review-tool-policies.
- Includes are read when the review is built and count toward
max_prompt_size, so include only short sources. Name long sources, and
sources that will grow, by path.
- When the material is not code, say so in
review_guidelines so every
reviewer reads it that way, and in each rubric so trial reviews read it
that way before the guidelines take effect.
fix and refine are writable, code-framed workflows. For non-code
material, the user or a writing agent corrects findings. Say so before the
user turns on the Agent Hook, which hands findings to /roborev-fix.
- Local reviews read custom types, panels, hook settings, and rubrics from the
checkout. Review guidelines and
REVIEW.md come from the default branch,
which is origin/<default> when the repository has an origin remote, so
they apply only after the setup is pushed there. CI reads everything from
its trusted base ref. Commit the whole setup to the default branch so all
three agree, and tell the user the guidelines wait on that push.
- For GitHub Actions reviews,
roborev init gh-action generates a workflow
that skips draft PRs and reviews them when marked ready. Use
--include-drafts to review drafts too. Both modes cancel overlapping runs
for the same workflow and PR. Existing workflows need
roborev init gh-action --force to adopt the behavior; add
--include-drafts if the user wants draft reviews.
- A
type = "kata" hook files an issue for each reviewer's failing review as
well as for the combined review. With a panel of several reviewers, one
failing commit can open several issues. Say so when proposing it.
Example: a legal brief checked every five commits by two reviewers. It leaves
the agent to the repository or machine default. Adapt it; do not copy names
that do not fit.
# .roborev.toml
post_commit_batch_size = 5
review_min_severity = "medium"
review_guidelines = """
This repository holds drafts of a legal brief, not software. Review the prose
and its sources. Do not comment on Markdown formatting or file layout.
"""
[review]
hook_review_panel = "brief"
[review.types.facts]
template = "review-rubrics/facts.md"
[review.types.facts.includes]
timeline = "evidence/timeline.md"
[review.types.quotes]
template = "review-rubrics/quotes.md"
[review.subagents.facts]
review_type = "facts"
[review.subagents.quotes]
review_type = "quotes"
[review.panels.brief]
members = ["facts", "quotes"]
Write the rubrics
A rubric is a Go template, usually 20 to 60 lines. Write it from the user's own
words:
- What the material is and who relies on it, in one or two sentences.
- The checks, as a concrete list.
- What to check against: named files or included text.
- What not to flag.
- Severity in the material's terms, with an example from their work for each
level.
- Where to point: the file and line, or the section, of the problem.
- When a source is missing, report a finding that names it. Use the
unable_to_review verdict only when the change cannot be assessed at all;
roborev treats it as an agent failure and retries.
- Report every real finding. The configured threshold decides pass or fail.
roborev appends the review target, the diff, and the output format after the
rubric, so do not add diff placeholders. Only .ReviewType and .Includes are
available. Write a literal {{ as {{"{{"}}.
# Fact check
You are checking a draft legal brief that will be filed with a court. A wrong
date or a misstated event undermines the brief with the court.
The timeline below is the source of truth for dates and events:
{{ index .Includes "timeline" }}
In the changed text, check that:
- every date matches the timeline;
- every event the timeline covers is described the way it records it;
- every fact the argument relies on appears in the timeline or a cited exhibit.
Each exhibit in `exhibits/` has a text copy beside it. Read the text copy when
a fact cites an exhibit.
Do not flag citation format, writing style, or the legal argument.
Severity:
- high: a date or event contradicts the timeline or the cited exhibit.
- medium: a fact the argument relies on has no support in the record.
- low: an imprecise detail that would not mislead a reader.
Give each location as the file and line of the sentence in the draft.
Confidential material
Before proposing, tell the user where the material can go:
- the provider behind each reviewer and synthesis agent, and the account or
endpoint each agent CLI is signed in to; roborev does not choose it;
- Codex when
[ci] check = true, regardless of the review panel's agents;
- any other agent a review can reach: the repository or machine default agent
for reviews outside the panel, and configured backup agents;
- every agent priced in
budget.agent_costs, when budget.enabled is true;
near the daily cap, budget routing can move a review that is not part of
a panel to any of them, even when its type names an agent;
- the design-review classifier (
classify_agent, claude-code by default)
and the design reviewer's agent, when auto_design_review.enabled or
auto_design_review.hook_enabled is true; a panel run with no design
member can start both, whatever agents its members pin;
- the MCP servers a strict review type is granted, which receive whatever
the reviewer sends in its tool calls;
- roborev's local database, which stores prompts and reviews;
- the PostgreSQL mirror, when
sync.enabled is true;
- pull request comments, when CI reviews cover this repository;
- the Kata project, when a
type = "kata" hook files findings there, and
Kata issue text, which [kata_context] adds to review prompts.
Ask whether that is acceptable. Do not decide for them. If the user allows only
some providers, every job that can carry the material must name an approved
agent itself. An agent inherited from a default can come from review_agent
or another workflow setting, and can fall back to any installed agent.
- Set
agent on every subagent in every panel, built-in members such as a
default reviewer included, and on every custom type.
- Set
synthesis_agent on every panel, and the repository agent and
default_panel.
- Check
roborev config --from-skill list --show-origin for backup_agent
and *_backup_agent, and every panel for synthesis_backup_agent. Each
backup must be an approved agent or be removed.
- Check
budget.enabled and budget.agent_costs. Budget routing does not
change panel members or synthesis, but can move any other review. While it
is on, run every review through a panel, a one-member panel for a single
type, or get approval to change the budget policy.
- When either
auto_design_review setting is on, propose enabled = false
and hook_enabled = false under [auto_design_review] in .roborev.toml.
The design review it starts is a standalone job, so budget routing can
move it too.
- In the proposal, name the agent each reviewer, combining call, and backup
will use.
Propose turning off automatic design review for non-code material even
without a provider restriction; a design review of prose is noise.
Propose and get approval
Send one proposal:
- A short summary of what the review is for.
- Each file you will create or change, with one plain line on what it does.
- Changes outside the repository, such as global configuration, listed
separately.
- Your calls: each default you chose that the user did not state, one line
each.
- How it will run: when reviews start, which agents run, and how many agent
calls one review uses. A panel uses one call per reviewer, plus one
combining call when two or more reviewers finish and any of them reports
a finding or does not pass.
- The commit you will make after the checks pass: branch and message.
- The full content of every file:
.roborev.toml (or the exact change to an
existing one) and each rubric.
Build and verify
After approval:
Write the approved repository files. Edit only the keys you proposed in an
existing .roborev.toml.
Write global settings only if the user approved them.
Check the result:
roborev config --from-skill validate
roborev doctor --from-skill --json
git check-ignore --no-index -v review-rubrics/facts.md
Validation and doctor must pass, but they do not open rubrics, includes, or
the sources a rubric names. Check those yourself:
git check-ignore prints nothing, and exits 1, for each rubric, include,
and source file.
- Each template, include, and named source exists and is committed by the
time you finish.
- Each template's only
{{ are intended template actions.
- Use doctor to confirm the ordinary-review agent and any default or hook
panels it reports. Doctor does not report standalone custom types or
manually selected panels. For those, resolve each member's effective
agent from its type and subagent settings and the fallback chain above;
confirm that agent supports custom types.
Make the commit named in the proposal, using the repository's commit
conventions.
Ask about the two remaining steps one at a time, and run each only if the
user says yes:
- Hooks, if automatic reviews are wanted and doctor reports them
missing.
roborev init --from-skill installs Git hooks that start
reviews after commits, starts roborev's background service, and adds
its snapshot directory to .gitignore. If core.hooksPath comes from
global Git configuration, do not run it; it would install into that
shared directory. Tell the user reviews run only on request until those
hooks call roborev, and list that as pending.
- A trial review (below).
Trial review and tuning
A trial review is the fastest way to learn whether a rubric works. It spends
agent calls and sends material to the agents, so ask first. Choose a commit or
range that changes the material and contains every named source. With
isolate_reviews = true, the daemon checks out the reviewed commit or range
head, so a source added after the material commit is unavailable when reviewing
only that older commit. Verify each source at the chosen target with
git show <target>:<path>. If needed, review a range that includes the material
change and ends at a commit containing the sources, such as the setup commit.
Hooks review only commits made after setup, so material committed earlier is
reviewed only when someone asks.
Offer one review of the commit or range that holds it. Use --panel none for
a standalone custom type so a configured default_panel cannot replace the
rubric with its members. When providers are restricted and budget routing is
on, use a panel instead; see Confidential material.
roborev review --from-skill --type facts --panel none --wait
roborev review --from-skill --panel brief --wait
Without a commit, these review HEAD. To review another commit or a range,
verify each ref with git rev-parse --verify first and pass it as a quoted
argument, or use --since <commit>. For a panel, the job printed at enqueue is the combined
review. Read a member's own review with:
roborev job show --from-skill --job <member-job-id>
Show the user the verdict and findings, then tune together:
- A finding they would reject becomes a "do not flag" line in that rubric.
- A mistake the reviewer missed becomes a check.
- A severity they disagree with changes the severity guidance.
Show each rubric change, get approval, commit it, and request a new review.
Rerunning an old job reuses its frozen settings.
Hand off
Finish with a short summary:
- Files created or changed, and whether they are committed on the default
branch.
- How reviews run: when they start, which reviewers, and which agents.
- How to run one on request, and how to read results:
roborev tui,
roborev job list, or roborev job show --job <id>.
- How to tune: edit a rubric, commit, and review again.
- How to add a source document: commit its text where the rubric expects it,
and update the rubric or include when the path changes.
- What is still pending, such as hooks, a stopped daemon, guidelines waiting
on a push to the default branch, or the confidentiality decision.
Red flags
| Thought |
Reality |
| "I'll write a standard config and skip the questions" |
The rubric is the product. Find out what they need caught. |
| "Options will save them effort" |
Options steer. Ask them to describe first. |
| "I'll pick the agent I know best" |
Keep the agent they run, or ask among the agents that support custom types. |
| "The reviewer can look that up online" |
Reviewers read only the repository and their prompt. Commit the source text. |
"Rubrics can live under .roborev/" |
That directory is ignored and blocks roborev init. |
"roborev fix can apply the findings" |
Fix and refine are code-framed. Prose is corrected by the user or a writing agent. |
| "They said it sounds good" |
Approval covers what you showed. Show the files before writing them. |
"The source is missing, so return unable_to_review" |
That counts as an agent failure. Report a finding that names the missing source. |
1---2name: roborev-setup-review3description: Use only when the user explicitly invokes /roborev-setup-review4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/roborev-dev/roborev-setup-review7---89# roborev-setup-review1011Work with the user to design a review for their repository, then write the12roborev configuration and rubrics that run it. The material can be code or13anything else committed to Git: a legal brief, a contract, a research report, a14manual. Find out what the reviewer should catch and why, play it back, and15write files only after the user approves.1617## Usage1819```text20/roborev-setup-review [what the review is for]21```2223## Explicit invocation only2425Invocation must be explicit: literal personal `/roborev-setup-review`, or structured26Grok Build skill selection.27Requests such as “set up a legal review for this repository” without one of28these explicit mechanisms must use native behavior and must not run roborev.2930Honor existing session authorization and project AGENTS.md instructions. This31invocation authorizes read-only inspection and the conversation. Writing32repository files, changing global configuration, installing hooks, committing,33and running a review each still need the user's approval.3435## Sandbox access3637roborev uses a local daemon. If a command fails with `permission denied`, the38sandbox may be blocking its loopback port or Unix socket. Retry the same command39with the runtime's supported sandbox escalation mechanism when supported and authorized.40Do not start or restart the daemon because a sandboxed status probe cannot reach41it.4243## Look first4445Before your first message, inspect what already exists. These checks are46read-only and need no approval:4748```bash49roborev doctor --from-skill --json50roborev config --from-skill validate51roborev config --from-skill list --show-origin52roborev config --from-skill get sync.enabled53git config --show-origin --get core.hooksPath54```5556Doctor reports which agents are installed, which agent runs reviews here, and57whether the Git hooks are installed. `core.hooksPath` shows whether the58repository's hooks come from somewhere else. Also read `.roborev.toml`,59`REVIEW.md`, existing rubric files, `.kata.toml`, and agent instruction files60such as AGENTS.md. A `.kata.toml` means the repository tracks its work in Kata.61List the layout, file types, headings, and recent commit subjects. Reading the62material itself, or comparing drafts against sources, is recon that the user63approves first.6465Use what you find to skip questions you can answer. Do not recite it.6667## What do you already know?6869- **Everything that matters is in the request**, such as "check every quote in70 `drafts/` against the exhibit text in `exhibits/`, on each commit". Skip the71 conversation and go to [Propose and get approval](#propose-and-get-approval).72- **A change to an existing review**, such as one rubric or the batch size.73 Ask only what the change needs, describe it in chat, and get approval.74- **A new review with open questions.** Start the conversation.7576## Your first message7778Your first message has two parts:79801. One line saying that if they would rather skip the questions, you can propose81 a setup from what you found. If they take that offer, state your defaults in82 plain words and go to the proposal. They still approve it before you write.831. One open question that gets them describing a concrete moment, such as "What84 is in these drafts, and what is the mistake you most want caught before one85 goes out?"8687That's the whole message.8889## The conversation9091End each message with one question, without a list of example answers. Use the92user's words. Say "reviewer", "check", and "source documents"; avoid93"subagent", "panel", and "custom review type" unless the user uses them first.9495Get them describing before you offer options. Offer a short menu only when they96are stuck. When they say "just guess", propose something concrete and say it is97your guess. A guess they can correct ("I'm guessing the timeline file is the98source of truth for dates?") often beats a question.99100Ground to cover. Treat this as territory, not a script:101102- **The material:** what it is, who relies on it, and what happens when it is103 wrong.104- **The checks:** what a careful human reviewer would check.105- **Sources of truth:** what each check compares against, such as files in the106 repository, scans or PDFs, or an outside database. Reviewers read only the107 repository and their prompt; see [the rules](#turn-answers-into-configuration).108- **What to leave alone:** findings they would reject on sight, house109 conventions, and known non-issues.110- **What fails:** which mistakes must block and which are worth noting. Ask111 with their own example: "Would a misspelled party name fail the review, or112 just be noted?"113- **When it runs:** every commit, every few commits, on request, or on pull114 requests.115- **Who acts on findings:** the user, a writing agent, or someone else, and116 whether findings should also land in Kata when the repository uses it.117- **Where the material may go:** see [Confidential material](#confidential-material).118- **Which agent runs it:** the agent and model they already use and trust. Find119 out which choices they want to make and which they hand to you.120121Questions that work anchor in specifics: "Walk me through the last draft that122went out with a mistake." "If the reviewer could catch only one kind of mistake,123which one?" "What finding would make you roll your eyes?"124125Once you have some grounding, offer recon: reading a few drafts and sources to126propose concrete checks. Say what you would look for. They decide.127128Before proposing, consider several shapes privately: one reviewer with a129combined checklist, or several reviewers. Each reviewer is one more agent call.130Split checks only when they need different sources, a different agent, or a131different focus that one rubric would blur. Drop ideas that fight what the user132told you.133134## Play it back135136As soon as you understand one part, describe it back in about 150 to 250 words,137then return to questions. Parts are usually:1381391. What the review is for and what it protects.1401. Each reviewer: what it checks, against what, what it ignores, and what fails.1411. When it runs and what happens to the findings.142143Mark your guesses as guesses; only what they said goes in as theirs. End each144chunk by asking what is wrong or missing.145146## Turn answers into configuration147148This mapping is for you, not the user. Use only what the conversation needs.149150| They want | Configure |151|-----------|-----------|152| One kind of check | One `[review.types.<name>]` with a rubric `template` |153| Several checks | One type per check, one `[review.subagents.<name>]` per type, and a `[review.panels.<name>]` listing them |154| Context every reviewer needs | `review_guidelines` in `.roborev.toml`, or `REVIEW.md` |155| A source reviewers compare against | Commit its text and name the path in the rubric |156| A short source every review needs in full | `[review.types.<name>.includes]`, rendered with `{{ index .Includes "<key>" }}` |157| One custom check after every commit or every N commits | A type, a subagent that uses it, and a one-member panel; set `hook_review_panel` under `[review]`. Automatic reviews use this panel and carry no review type. Set `post_commit_batch_size = N` for every N commits. |158| Several custom checks after every commit or every N commits | A type and subagent per check, a panel listing those subagents, and `hook_review_panel` under `[review]`. Set `post_commit_batch_size = N` for every N commits. |159| Keep the usual code review after commits too | Add a subagent with `review_type = "default"` to the hook panel |160| Combine bursts of automatic reviews across repositories | Set `post_commit_batch_size` and/or `post_commit_quiet_period = "5m"` globally. Each repo can override either value. The count threshold or quiet period queues the accumulated range, whichever happens first. Values below 2 disable the count threshold; an empty quiet period or `"0"` disables the timer. Pushes flush pending commits. Daemon restarts cancel timers but preserve pending checkpoints for the next commit or push. |161| The whole branch each time | `post_commit_review = "branch"` |162| Reviews on request | `[review] default_panel`, or `--type` and `--panel` |163| Reviews on pull requests | `[ci] panel`; see <https://roborev.io/docs/advanced/subagent-review-panels/#ci-panels> |164| Verify CI findings before posting | `[ci] check = true`, off by default; Codex checks findings in a sandbox and keeps the original review if checking fails. Global `[ci] check_model` and `check_reasoning` select its model and effort. |165| PR reviews only after a draft is marked ready | Ask whether draft PRs should be skipped. For the daemon poller, global `[ci] skip_drafts = true` in `~/.roborev/config.toml` (default `false`; no repo override). Ready PRs become eligible next poll without a push, under normal throttle, quiet-hours, and dedup rules. Active reviews are not canceled. |166| Rewrite checked CI findings | `[ci] rewrite = true` requires `check = true`. Two additional Codex calls use stored findings and escaped PR context, without checker output, in a fresh read-only clone; failure keeps the checked text. |167| Shorter synthesized GitHub daemon comments | `[ci] comment_max_findings` caps structured findings; `0` (default) is unlimited. Stored reviews stay complete. |168| Silence on clean synthesized GitHub daemon reviews | `[ci] comment_when_clean = false`; default `true` posts clean comments. Stored reviews stay unchanged. |169| Only serious findings fail | `review_min_severity`, plus severity guidance in each rubric |170| Passing reviews close themselves | `auto_close_passing_reviews = true` |171| Reviewers that see the task a commit is for, from Kata | `[kata_context]` with `mode = "current"`; commits name their issue, such as `Closes: kata#abc4` |172| Failed reviews and findings filed as Kata issues | A `[[hooks]]` entry with `event = "review.*"` and `type = "kata"` |173| Reviewers that read changed PDFs, scans, or images | `binary_evidence = true` on the type; see <https://roborev.io/docs/advanced/custom-review-types/#binary-evidence> |174| A reviewer that looks things up through an outside service | A strict `tools` policy on the type that grants exact MCP tools; see <https://roborev.io/docs/advanced/custom-review-types/#granting-mcp-tools> |175| Files reviewers should skip | `exclude_patterns` |176| Reviewers that skip the setup itself, for non-code material | `exclude_patterns = [".roborev.toml", "review-rubrics/"]` |177| A particular agent or model | `agent`, `model`, and `reasoning` in the repository, type, or subagent |178| A reviewer on trial | `non_voting = true` on the subagent |179| A reviewer that may flake | `allow_failure = true` and `timeout` on the subagent |180| A combined review that checks each finding against the material, or labels findings for whoever fixes them | `synthesis_instructions` on the panel; see <https://roborev.io/docs/advanced/subagent-review-panels/#synthesis-instructions> |181| Automation supplies every reviewer’s prompt and settings without editing repository policy | `POST /api/panel/enqueue`; optional `hold_synthesis` waits for `POST /api/panel/synthesize`. See <https://roborev.io/docs/automation/manual-panel-synthesis/#supply-a-panel-through-the-api> |182183For a small panel that checks findings before keeping them, use the184[precise panel recipe](https://roborev.io/docs/advanced/subagent-review-panels/#precise-panel-recipe).185It keeps agreed findings unless disproved and requires code evidence for186single-reviewer or contradicted findings. Silence is not disagreement.187188Rules that matter:189190- Put the setup in the repository's `.roborev.toml`. Use the global191 `~/.roborev/config.toml` only when the user wants the same review in every192 repository, and only with their approval.193- Custom types need an agent with JSON Schema output: `codex`, `claude-code`,194 `pi`, or `grok`. Pi also needs its `pi-json-schema` extension, which195 validation and doctor do not check. Custom types do not inherit196 `review_agent`. Their agent resolves from type-specific repository settings,197 the repository's generic `agent`, type-specific global settings, then global198 `default_agent` (or `codex` when none is set). Check the effective agent for199 each custom reviewer before leaving `agent` unset. If it differs from the200 reviewer the user wants, ask and set the supported agent on the type or201 subagent. When the user restricts providers, see202 [Confidential material](#confidential-material). Otherwise ask which203 supported agent to use. Do not choose one for them.204- `review_min_severity` applies to every reviewer. Align each rubric's205 severity levels so what the user said must fail sits at or above that one206 threshold. Findings below it still appear in the review; they just do not207 fail it.208- `hook_review_panel` replaces whatever ran after each commit before,209 including the usual code review and any global `hook_review_panel`. For210 code, ask whether the usual review should keep running, and if so add a211 `default` member to the panel.212- Type names start with a lowercase letter, use lowercase letters, digits,213 and hyphens, and are at most 64 characters. These names are reserved:214 `default`, `review`, `general`, `security`, `design`, `lookahead`,215 `test-value`, `goal`, `fix`, `refine`, and `classify`.216- Keep rubrics and sources outside the snapshot directory (`.roborev/` by217 default). It is ignored by Git, and `roborev init` refuses to run while218 tracked files sit under it. Use a committed directory such as219 `review-rubrics/`.220- Reviewers see the diff, the rubric, and the guidelines, and read other files221 in the checkout with read-only tools. They cannot fetch URLs. Commit the222 text a check needs. If a source can be neither committed nor reached223 through an MCP grant, tell the user the reviewer can check only what the224 repository holds.225- For PDFs, scans, and images, set `binary_evidence = true` on the type.226 Reviews of a commit or range then get a saved copy of each binary file227 those commits add or change. Files the commits do not touch are not228 included, so for a source that stays unchanged, such as an exhibit that229 later drafts cite, also commit an exported text copy beside it. Reviews of230 uncommitted changes fail when the type sets `binary_evidence`.231 `exclude_patterns` removes files from the evidence as well as the diff, so232 never exclude binary files a reviewer must read.233- The reviewer opens each saved copy with its own tools, so match the agent to234 the files. Claude Code and Grok read PDFs and images directly. Codex reads235 images, but reads a PDF only by running a converter such as `pdftotext` on236 the machine that runs the review, and gets no text from a scanned PDF. For237 PDF evidence, propose `claude-code` or `grok` on the type, or check that the238 converter is installed. Before relying on Pi, have the user confirm it can239 read the file types involved.240- A reviewer reaches an outside service only through exact MCP grants on a241 strict type: a `[review.types.<name>.tools]` table with242 `mode = "read-only"` and an `mcp` table that names each server and its243 tools. Strict types run only on Claude Code, so set `agent = "claude-code"`244 on the type. A backup agent that cannot enforce the policy fails the review245 instead of running it. The global `~/.roborev/config.toml` must define the246 server in `review_mcp_config` and list each `server/tool` pair in247 `review_mcp_allowed_tools`; repository config cannot set either. Propose248 those global lines separately and write them only with the user's249 approval. See250 <https://roborev.io/docs/configuration/#strict-review-tool-policies>.251- Includes are read when the review is built and count toward252 `max_prompt_size`, so include only short sources. Name long sources, and253 sources that will grow, by path.254- When the material is not code, say so in `review_guidelines` so every255 reviewer reads it that way, and in each rubric so trial reviews read it256 that way before the guidelines take effect.257- `fix` and `refine` are writable, code-framed workflows. For non-code258 material, the user or a writing agent corrects findings. Say so before the259 user turns on the Agent Hook, which hands findings to `/roborev-fix`.260- Local reviews read custom types, panels, hook settings, and rubrics from the261 checkout. Review guidelines and `REVIEW.md` come from the default branch,262 which is `origin/<default>` when the repository has an `origin` remote, so263 they apply only after the setup is pushed there. CI reads everything from264 its trusted base ref. Commit the whole setup to the default branch so all265 three agree, and tell the user the guidelines wait on that push.266- For GitHub Actions reviews, `roborev init gh-action` generates a workflow267 that skips draft PRs and reviews them when marked ready. Use268 `--include-drafts` to review drafts too. Both modes cancel overlapping runs269 for the same workflow and PR. Existing workflows need270 `roborev init gh-action --force` to adopt the behavior; add271 `--include-drafts` if the user wants draft reviews.272- A `type = "kata"` hook files an issue for each reviewer's failing review as273 well as for the combined review. With a panel of several reviewers, one274 failing commit can open several issues. Say so when proposing it.275276Example: a legal brief checked every five commits by two reviewers. It leaves277the agent to the repository or machine default. Adapt it; do not copy names278that do not fit.279280```toml281# .roborev.toml282post_commit_batch_size = 5283review_min_severity = "medium"284review_guidelines = """285This repository holds drafts of a legal brief, not software. Review the prose286and its sources. Do not comment on Markdown formatting or file layout.287"""288289[review]290hook_review_panel = "brief"291292[review.types.facts]293template = "review-rubrics/facts.md"294295[review.types.facts.includes]296timeline = "evidence/timeline.md"297298[review.types.quotes]299template = "review-rubrics/quotes.md"300301[review.subagents.facts]302review_type = "facts"303304[review.subagents.quotes]305review_type = "quotes"306307[review.panels.brief]308members = ["facts", "quotes"]309```310311## Write the rubrics312313A rubric is a Go template, usually 20 to 60 lines. Write it from the user's own314words:315316- What the material is and who relies on it, in one or two sentences.317- The checks, as a concrete list.318- What to check against: named files or included text.319- What not to flag.320- Severity in the material's terms, with an example from their work for each321 level.322- Where to point: the file and line, or the section, of the problem.323- When a source is missing, report a finding that names it. Use the324 `unable_to_review` verdict only when the change cannot be assessed at all;325 roborev treats it as an agent failure and retries.326- Report every real finding. The configured threshold decides pass or fail.327328roborev appends the review target, the diff, and the output format after the329rubric, so do not add diff placeholders. Only `.ReviewType` and `.Includes` are330available. Write a literal `{{` as `{{"{{"}}`.331332```markdown333# Fact check334335You are checking a draft legal brief that will be filed with a court. A wrong336date or a misstated event undermines the brief with the court.337338The timeline below is the source of truth for dates and events:339340{{ index .Includes "timeline" }}341342In the changed text, check that:343344- every date matches the timeline;345- every event the timeline covers is described the way it records it;346- every fact the argument relies on appears in the timeline or a cited exhibit.347348Each exhibit in `exhibits/` has a text copy beside it. Read the text copy when349a fact cites an exhibit.350351Do not flag citation format, writing style, or the legal argument.352353Severity:354355- high: a date or event contradicts the timeline or the cited exhibit.356- medium: a fact the argument relies on has no support in the record.357- low: an imprecise detail that would not mislead a reader.358359Give each location as the file and line of the sentence in the draft.360```361362## Confidential material363364Before proposing, tell the user where the material can go:365366- the provider behind each reviewer and synthesis agent, and the account or367 endpoint each agent CLI is signed in to; roborev does not choose it;368- Codex when `[ci] check = true`, regardless of the review panel's agents;369- any other agent a review can reach: the repository or machine default agent370 for reviews outside the panel, and configured backup agents;371- every agent priced in `budget.agent_costs`, when `budget.enabled` is true;372 near the daily cap, budget routing can move a review that is not part of373 a panel to any of them, even when its type names an agent;374- the design-review classifier (`classify_agent`, `claude-code` by default)375 and the design reviewer's agent, when `auto_design_review.enabled` or376 `auto_design_review.hook_enabled` is true; a panel run with no design377 member can start both, whatever agents its members pin;378- the MCP servers a strict review type is granted, which receive whatever379 the reviewer sends in its tool calls;380- roborev's local database, which stores prompts and reviews;381- the PostgreSQL mirror, when `sync.enabled` is true;382- pull request comments, when CI reviews cover this repository;383- the Kata project, when a `type = "kata"` hook files findings there, and384 Kata issue text, which `[kata_context]` adds to review prompts.385386Ask whether that is acceptable. Do not decide for them. If the user allows only387some providers, every job that can carry the material must name an approved388agent itself. An agent inherited from a default can come from `review_agent`389or another workflow setting, and can fall back to any installed agent.390391- Set `agent` on every subagent in every panel, built-in members such as a392 `default` reviewer included, and on every custom type.393- Set `synthesis_agent` on every panel, and the repository `agent` and394 `default_panel`.395- Check `roborev config --from-skill list --show-origin` for `backup_agent`396 and `*_backup_agent`, and every panel for `synthesis_backup_agent`. Each397 backup must be an approved agent or be removed.398- Check `budget.enabled` and `budget.agent_costs`. Budget routing does not399 change panel members or synthesis, but can move any other review. While it400 is on, run every review through a panel, a one-member panel for a single401 type, or get approval to change the budget policy.402- When either `auto_design_review` setting is on, propose `enabled = false`403 and `hook_enabled = false` under `[auto_design_review]` in `.roborev.toml`.404 The design review it starts is a standalone job, so budget routing can405 move it too.406- In the proposal, name the agent each reviewer, combining call, and backup407 will use.408409Propose turning off automatic design review for non-code material even410without a provider restriction; a design review of prose is noise.411412## Propose and get approval413414Send one proposal:4154161. A short summary of what the review is for.4171. Each file you will create or change, with one plain line on what it does.4181. Changes outside the repository, such as global configuration, listed419 separately.4201. Your calls: each default you chose that the user did not state, one line421 each.4221. How it will run: when reviews start, which agents run, and how many agent423 calls one review uses. A panel uses one call per reviewer, plus one424 combining call when two or more reviewers finish and any of them reports425 a finding or does not pass.4261. The commit you will make after the checks pass: branch and message.4271. The full content of every file: `.roborev.toml` (or the exact change to an428 existing one) and each rubric.429430<HARD-GATE>431Write nothing until the user approves the proposal. Approval covers only what432you showed, including the commit it named. A later change to what a reviewer433checks, what fails, or where the material goes comes back for approval. If they434opted out of the questions, they still approve the proposal before you write.435</HARD-GATE>436437## Build and verify438439After approval:4404411. Write the approved repository files. Edit only the keys you proposed in an442 existing `.roborev.toml`.4434441. Write global settings only if the user approved them.4454461. Check the result:447448 ```bash449 roborev config --from-skill validate450 roborev doctor --from-skill --json451 git check-ignore --no-index -v review-rubrics/facts.md452 ```453454 Validation and doctor must pass, but they do not open rubrics, includes, or455 the sources a rubric names. Check those yourself:456457 - `git check-ignore` prints nothing, and exits 1, for each rubric, include,458 and source file.459 - Each template, include, and named source exists and is committed by the460 time you finish.461 - Each template's only `{{` are intended template actions.462 - Use doctor to confirm the ordinary-review agent and any default or hook463 panels it reports. Doctor does not report standalone custom types or464 manually selected panels. For those, resolve each member's effective465 agent from its type and subagent settings and the fallback chain above;466 confirm that agent supports custom types.4674681. Make the commit named in the proposal, using the repository's commit469 conventions.4704711. Ask about the two remaining steps one at a time, and run each only if the472 user says yes:473474 - **Hooks**, if automatic reviews are wanted and doctor reports them475 missing. `roborev init --from-skill` installs Git hooks that start476 reviews after commits, starts roborev's background service, and adds477 its snapshot directory to `.gitignore`. If `core.hooksPath` comes from478 global Git configuration, do not run it; it would install into that479 shared directory. Tell the user reviews run only on request until those480 hooks call roborev, and list that as pending.481 - **A trial review** (below).482483## Trial review and tuning484485A trial review is the fastest way to learn whether a rubric works. It spends486agent calls and sends material to the agents, so ask first. Choose a commit or487range that changes the material and contains every named source. With488`isolate_reviews = true`, the daemon checks out the reviewed commit or range489head, so a source added after the material commit is unavailable when reviewing490only that older commit. Verify each source at the chosen target with491`git show <target>:<path>`. If needed, review a range that includes the material492change and ends at a commit containing the sources, such as the setup commit.493Hooks review only commits made after setup, so material committed earlier is494reviewed only when someone asks.495Offer one review of the commit or range that holds it. Use `--panel none` for496a standalone custom type so a configured `default_panel` cannot replace the497rubric with its members. When providers are restricted and budget routing is498on, use a panel instead; see [Confidential material](#confidential-material).499500```bash501roborev review --from-skill --type facts --panel none --wait502roborev review --from-skill --panel brief --wait503```504505Without a commit, these review `HEAD`. To review another commit or a range,506verify each ref with `git rev-parse --verify` first and pass it as a quoted507argument, or use `--since <commit>`. For a panel, the job printed at enqueue is the combined508review. Read a member's own review with:509510```bash511roborev job show --from-skill --job <member-job-id>512```513514Show the user the verdict and findings, then tune together:515516- A finding they would reject becomes a "do not flag" line in that rubric.517- A mistake the reviewer missed becomes a check.518- A severity they disagree with changes the severity guidance.519520Show each rubric change, get approval, commit it, and request a new review.521Rerunning an old job reuses its frozen settings.522523## Hand off524525Finish with a short summary:526527- Files created or changed, and whether they are committed on the default528 branch.529- How reviews run: when they start, which reviewers, and which agents.530- How to run one on request, and how to read results: `roborev tui`,531 `roborev job list`, or `roborev job show --job <id>`.532- How to tune: edit a rubric, commit, and review again.533- How to add a source document: commit its text where the rubric expects it,534 and update the rubric or include when the path changes.535- What is still pending, such as hooks, a stopped daemon, guidelines waiting536 on a push to the default branch, or the confidentiality decision.537538## Red flags539540| Thought | Reality |541|---------|---------|542| "I'll write a standard config and skip the questions" | The rubric is the product. Find out what they need caught. |543| "Options will save them effort" | Options steer. Ask them to describe first. |544| "I'll pick the agent I know best" | Keep the agent they run, or ask among the agents that support custom types. |545| "The reviewer can look that up online" | Reviewers read only the repository and their prompt. Commit the source text. |546| "Rubrics can live under `.roborev/`" | That directory is ignored and blocks `roborev init`. |547| "`roborev fix` can apply the findings" | Fix and refine are code-framed. Prose is corrected by the user or a writing agent. |548| "They said it sounds good" | Approval covers what you showed. Show the files before writing them. |549| "The source is missing, so return `unable_to_review`" | That counts as an agent failure. Report a finding that names the missing source. |