Use only when the user explicitly invokes /roborev-setup-review
70%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Critical
Do not install without reviewing
Fix and improve this skill with Tessl
tessl review fix ./internal/skills/claude/roborev-setup-review/SKILL.mdWork 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.
/roborev-setup-review [what the review is for]Invocation must be explicit: literal personal /roborev-setup-review, or structured
Claude Code 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 CLAUDE.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.
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 dangerouslyDisableSandbox: true when supported and authorized.
Do not start or restart the daemon because a sandboxed status probe cannot reach
it.
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.hooksPathDoctor 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 CLAUDE.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.
drafts/ against the exhibit text in exhibits/, on each commit". Skip the
conversation and go to Propose and get approval.Your first message has two parts:
That's the whole message.
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:
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.
As soon as you understand one part, describe it back in about 150 to 250 words, then return to questions. Parts are usually:
Mark your guesses as guesses; only what they said goes in as theirs. End each chunk by asking what is wrong or missing.
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. |
| Review commits after they land on the default branch | Global [ci] review_default_branch = true in ~/.roborev/config.toml (default false). Each new first-parent commit is reviewed against its parent with the CI panel; history before the first poll is not reviewed. A repo opts out with [ci] review_default_branch = false in .roborev.toml. Results are stored reviews plus an informational roborev/default-branch commit status; no PR comment. See https://roborev.io/docs/integrations/github/#review-commits-on-the-default-branch |
| 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. |
| Hide low-confidence findings in synthesized GitHub daemon comments | [ci] comment_min_confidence accepts a finite 0–1 floor for the confidence recorded by synthesis. Unset globally disables filtering. Unset in a repo inherits the global floor, and repo 0 disables it. Findings with no stored score stay visible. Synthesis is instructed to use 0.5 when no source scored a finding, so a higher floor can hide it. |
| Silence on clean synthesized GitHub daemon reviews | [ci] comment_when_clean = false; default true posts clean comments. With false, filtering can suppress a new comment even when the stored review has findings. |
| 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 | [review] binary_evidence = true for built-in reviews or binary_evidence = true on a custom 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:
.roborev.toml. Use the global
~/.roborev/config.toml only when the user wants the same review in every
repository, and only with their approval.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.default, review, general, security, design, lookahead,
test-value, goal, fix, refine, and classify..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/.binary_evidence = true under [review]
for built-in reviews, or on each custom type that needs it. The repository
setting overrides the global setting for built-in reviews; custom types
use their own setting independently.
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. Built-in
reviews of uncommitted changes omit evidence; custom dirty reviews fail
when their type enables it.
exclude_patterns removes files from the evidence as well as the diff, so
never exclude binary files a reviewer must read.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.[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.max_prompt_size, so include only short sources. Name long sources, and
sources that will grow, by path.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.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.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.type = "kata" hook files one issue per failing panel run, from the
combined review, not one per reviewer. Add sources = ["ci_branch"] to
file only findings from daemon reviews of commits that landed on the
default branch.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"]A rubric is a Go template, usually 20 to 60 lines. Write it from the user's own words:
unable_to_review verdict only when the change cannot be assessed at all;
roborev treats it as an agent failure and retries.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.Before proposing, tell the user where the material can go:
[ci] check = true, regardless of the review panel's agents;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;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;sync.enabled is true;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.
agent on every subagent in every panel, built-in members such as a
default reviewer included, and on every custom type.synthesis_agent on every panel, and the repository agent and
default_panel.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.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.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.Propose turning off automatic design review for non-code material even without a provider restriction; a design review of prose is noise.
Send one proposal:
.roborev.toml (or the exact change to an
existing one) and each rubric.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.mdValidation 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.{{ are intended template actions.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:
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 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 --waitWithout 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:
Show each rubric change, get approval, commit it, and request a new review. Rerunning an old job reuses its frozen settings.
Finish with a short summary:
roborev tui,
roborev job list, or roborev job show --job <id>.| 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. |
kenn-io/roborev
7e74ef7
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.