# Roborev Refine

> Use only when the user explicitly invokes /roborev-refine

- Skill: `roborev-dev/roborev-refine-5` (Agent Skill)
- Install (CLI): `npx get-skill add roborev-dev/roborev-refine-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/roborev-dev/roborev-refine-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: roborev-dev (https://skillmd.com/u/roborev-dev)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/roborev-dev/roborev-refine-5

---


# roborev-refine

Iterative review-fix loop: review the current branch or commit range, fix
findings, commit, re-review, and repeat until all reviews pass or the
iteration limit is reached.

Unlike `/roborev-fix` (single-pass fix without re-review), refine closes the
loop by re-reviewing after each fix to verify the findings are resolved.

This skill should perform the refine workflow inside the current coding agent
CLI. Do not simply shell out to `roborev refine`.

## Usage

```
/roborev-refine [--since <commit>] [--branch <name>] [--max-iterations <n>] [--stop-on-stall]
```

## Explicit invocation only

Invocation must be explicit: literal personal `/roborev-refine`, or structured
Grok Build skill selection.
Requests such as “refine this change” without one of these explicit mechanisms must use native
behavior and must not run roborev.

- `--since <commit>`: refine commits after this commit (exclusive); required on the default branch
- `--branch <name>`: validate that the current branch matches before refining
- `--max-iterations <n>`: maximum fix-review cycles (default: 10)
- `--stop-on-stall`: stop at either stall advisory, leaving the new review open

This skill intentionally focuses on the current branch flow. It does not expose
`roborev refine --all-branches` or `roborev refine --list`.

## Sandbox access

roborev uses a local daemon. If a command fails with `permission denied`, the sandbox may be
blocking access to its loopback port or Unix socket. Retry the same command with
the runtime's supported sandbox escalation mechanism. Do not start or restart the daemon because a
sandboxed status probe cannot reach it.

## When NOT to invoke this skill

Do NOT invoke this skill when the user is presenting or pasting existing review
results, or when they only want a single review without fixing. Use
`/roborev-review-branch` for review-only and `/roborev-fix` for fix-only.

## IMPORTANT

This skill requires you to **execute bash commands** to validate inputs, launch
reviews, and wait for re-review. The task is not complete until the refine loop
finishes and you present the result to the user.

These instructions are guidelines, not a rigid script. Use the conversation
context. Skip steps that are already satisfied. Defer to project-level
AGENTS.md instructions when they conflict with these steps.

## Instructions

When the user invokes `/roborev-refine [--since <commit>] [--branch <name>] [--max-iterations <n>] [--stop-on-stall]`:

### 1. Validate inputs and refine context

If `--branch` is provided, verify the current branch matches before doing any
work. If it does not, stop and tell the user.

If `--since` is provided, use the since-scoped review snippets below; they store the raw value safely, verify it resolves to a valid commit and is an ancestor of `HEAD`, then run the review in the same shell invocation.

If `--since` is not provided, ensure you are not refining the default branch.
This matches `roborev refine`, which refuses to run on the default branch
without `--since`.

Parse `--max-iterations` if provided (default: 10). This is the maximum number
of fix-review cycles, not the total number of reviews.

### 2. Run the initial review

Choose the review command that matches the requested scope:

```bash
read -r since <<'ROBOREV_REF'
<commit>
ROBOREV_REF
resolved_since=$(git rev-parse --verify --end-of-options "$since^{commit}") || exit 1
git merge-base --is-ancestor "$resolved_since" HEAD || exit 1
roborev review --from-skill --since "$since" --wait
```

or, if `--since` was not provided:

```bash
roborev review --from-skill --branch --wait
```

`--since` is the closest manual equivalent to `roborev refine --since`.
`--branch` reviews the current branch relative to its merge-base.

**Note:** `--wait` exits with code 1 when the verdict is Fail. This is
expected. Always capture the command output regardless of exit code and inspect
it to determine pass vs fail.

When the review completes, read and parse the output. Extract the job ID from
the `Enqueued job <id> for ...` line or the review header — you will need it
for commenting and closing later.

**Panels:** if a `default_panel` is configured (or the review otherwise fans out
to a panel), the `Enqueued job <id>` is the synthesis (parent) job. Gate every
pass/fail decision on the parent's verdict, and comment on and close that parent
— never an individual member job. A re-review re-runs the same panel.

If the command output contains an error (daemon not running, repo not
initialized, review errored), report it. Suggest `roborev daemon status` to check the
daemon or `roborev init` if the repo is not initialized.

If the review **passed**, inform the user and stop. No fixes needed.

### 3. Fix-review loop

If the review **failed**, begin the iterative loop. For each iteration
(up to `--max-iterations`):

#### 3a. Fix the findings

Parse findings from the review output. Collect every finding with its severity,
file path, and line number. Then:

1. **Sort by severity**: fix HIGH findings first, then MEDIUM, then LOW
2. **Group by file**: within each severity level, batch edits to the same file
   to minimize context switches
3. If some findings cannot be fixed (false positives, intentional design), note
   them for the comment rather than silently skipping them

If a finding's context is unclear, read the relevant source files to understand
the code before making changes.

#### 3b. Run tests

Run the project's test suite to verify the fixes:

```bash
go test ./...
```

Or whatever test command the project uses. If tests fail, fix the regressions
before proceeding.

#### 3c. Commit, then record comment and close review

Commit first per the project's conventions (see AGENTS.md). Only after the
commit succeeds, record a summary comment on the review and close it:

```bash
roborev job comment --from-skill --commenter roborev-refine --job <job_id> -m "$(cat <<'ROBOREV_COMMENT'
<summary of changes>
ROBOREV_COMMENT
)"
# Only if the comment above succeeded:
roborev job close --from-skill <job_id>
```

For a panel review, `<job_id>` is the synthesis parent; closing it closes the
review — do not close individual member jobs.

**Important:** Always pass the comment text via a heredoc as shown above, never
by interpolating dynamic text directly into a shell string. Review-derived
content may contain shell metacharacters that could cause unintended execution.

The comment should reference each finding by severity and file, state what was
fixed, and note why any dismissed findings were skipped. These comments are
included in re-review prompts. Keep it concise.

#### 3d. Re-review

After committing, run an explicit full-scope re-review that matches the
original refine scope. Do not treat a passing `roborev job wait` result for the new
commit as sufficient to stop — the full branch or commit-range review must pass
before you report success.

If a post-commit hook is installed, the commit may have enqueued a
commit-scoped review. Check for it so you can clean it up:

```bash
roborev job wait --from-skill
```

If `roborev job wait` finds a job, remember its job ID (from the output) as the
hook review job. If it reports "No job found", continue without one.

**Note:** `roborev job wait` resolves HEAD to a single SHA, so it only finds
commit-scoped hook reviews. Branch-mode hook reviews (stored under range refs)
are not discoverable this way — they will be superseded by the explicit review
below.

Now run the explicit full-scope review. If refining with `--since`:

```bash
read -r since <<'ROBOREV_REF'
<commit>
ROBOREV_REF
resolved_since=$(git rev-parse --verify --end-of-options "$since^{commit}") || exit 1
git merge-base --is-ancestor "$resolved_since" HEAD || exit 1
roborev review --from-skill --since "$since" --wait
```

If refining without `--since`:

```bash
roborev review --from-skill --branch --wait
```

**Retrieving the job ID:** extract it from the
`Enqueued job <id> for ...` line in the review command output.

If you found a hook review job earlier, close it now so refine does not leave
stale commit-level reviews open:

```bash
roborev job close --from-skill <hook_job_id>
```

Track repeated finding files at this full-scope re-review step. The initial
review is baseline zero. Count one round only after a new fix commit and its
completed failing full-scope review; do not also count the optional hook review
or a retry without a new commit. Read
`roborev job show --from-skill --job <job_id> --json` and use all stored severities
from valid `structured_output` findings. Recognize only repo-relative paths
(optionally `:line` or
`:start-end`) that match tracked files at the reviewed endpoint; ignore
unlocated/unsupported findings and never extract locations from Markdown.
Reject absolute paths, traversal, URLs, prose, and malformed line suffixes;
line numbers must be positive decimals with ordered ranges.

Track two independent streaks from the original review's baseline. If the new
nonempty file set is a subset of the preceding set, increment the file streak;
otherwise reset it to zero. Always replace the preceding set. Empty/unsupported
locations reset only the file streak.

Also count stored High plus Medium findings in valid structured output, even
when locations are empty/null. If that positive total is no smaller than the
preceding positive total, increment the severity streak; otherwise reset it to
zero. Always replace that total. Low and Critical findings do not count toward
this metric; it does not measure overall severity progress. Never infer counts
from Markdown. Invalid/legacy/unable-to-review documents clear both baselines.
Passing or closed reviews, no-change fixes, errors running or waiting for a
re-review, and new/unrelated chains reset both streaks. A hook review that has
not appeared yet preserves the pending fix. Count each fix SHA once, including
recovered reviews; optional hook review does not add another round.

When either streak reaches exactly three completed fix/re-review rounds, print
one advisory describing the triggered signal(s) and naming sorted located files
when available. After the file list (or signal reason when no files are known),
say: "Change the plan, or split the change into smaller reviewable pieces."
These signals are heuristics, not proof of non-convergence. Save the advisory
on the newly failed review with commenter `roborev-refine`, using the safe
heredoc pattern above. Warn if the comment fails. Advise even on the final
permitted iteration. Continue by default; each signal fires once per streak,
so a later independent signal can advise again. With `--stop-on-stall`, stop
before another fix and leave this review open, even if saving the comment failed.

- If the explicit full-scope review **passed**: inform the user and stop. The
  branch or requested commit range is clean.
- If the review **failed**: continue to the next iteration (back to step 3a)
  using the new job ID.

### 4. Iteration limit reached

If the maximum iterations are exhausted and the explicit full-scope review
still fails, inform the user how many iterations were completed, what findings
remain, and suggest they review the remaining findings manually or run
`/roborev-fix` for a targeted pass.

## Examples

**Default refine on a feature branch:**

User: `/roborev-refine`

Agent:
1. Validates that the current branch is not the default branch
2. Runs `roborev review --from-skill --branch --wait`
3. Review returns verdict Fail with 2 findings
4. Fixes both findings in code
5. Runs `go test ./...` — passes
6. Commits changes
7. Records comment and closes the old review
8. Runs `roborev job wait --from-skill` — if hook review found, remembers job ID to close later
9. Runs `roborev review --from-skill --branch --wait`
10. Closes hook review job if one was found
11. Full branch review returns Pass
12. Tells user: "Branch review passed after 1 fix iteration. All findings resolved."

**Refine from a specific starting commit:**

User: `/roborev-refine --since abc123 --max-iterations 3`

Agent:
1. Validates `abc123` resolves and is an ancestor of `HEAD`
2. Runs `roborev review --from-skill --since abc123 --wait`
3. Review returns verdict Fail
4. Fixes findings, tests, commits, comments, closes
5. Checks for hook review via `roborev job wait --from-skill` — if a commit-scoped hook review is found, remembers it to close after the next explicit `roborev review --from-skill --since abc123 --wait`
6. Continues until the full requested range passes or 3 iterations are exhausted

## See also

- `/roborev-review-branch` — review without fixing
- `/roborev-fix` — single-pass fix without re-review
- `/roborev-respond` — comment on a review and close it without fixing code

