radin-review

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Review

Review a scope, then triage the findings with the user: each kept group goes
to the backlog or gets tackled now. An agent caller reads
`RADIN_LIB/radin-review-core.md` and follows it instead of this skill. Both
read `RADIN_LIB/radin-explore-rule.md` before they explore.

## Step 1: Resolve the scope

Pass `<arg>` as one literal form the CLI accepts: a hash, PR number, path,
`A..B`, `last commit`, `last N commits`, `staged` or `since <date>`. Map the
user's words to it yourself: "the current branch changes" is
`<default-branch>..HEAD`. When two maps fit, ask which.

```bash
RADIN_CLI scope [<arg>]
```

It prints `type`/`scope`/`command`/`passes` lines, and Step 3 hands the
reviewer exactly the skills the `passes` line names. Route on its exit code:

- **1**: not a commit, PR, directory, range, or `since <date>`. Report it and
  stop.
- **2**: ambiguous, candidates on stderr (e.g. both a PR number and a
  directory). Ask which one.

State the resolved scope in one line, `Scope: commit a1b2c3d` or
`Scope: directory src/auth/`, then capture both inputs the review needs, here
and once:

- **The diff command.** The `command` line is the scope's one diff command.
  Record it verbatim and paste that same string into every later Bash call and
  the brief.
- **The commit list.** `RADIN_CLI scope --commits [<the same scope arg>]`
  prints one `<hash> <subject>` line per commit. A `dir` scope prints nothing:
  it has no commit list, and the brief says so.

Run the `command` before the review starts. No output (for a `dir` scope, no
file under the path) means report "nothing to review in `<scope>`" and stop.

## Step 2: Resolve the spec

Work these rungs in order and stop at the first that yields a spec:

1. **The invoking prompt named one**: a backlog id, a title, or a path. For an
   id or title, `RADIN_CLI backlog field "<it>" TASK_FILE` and
   `RADIN_CLI backlog field "<it>" PLAN_PATHS` (exit 1 means no plan; the task
   file alone is then the spec). For a path, that file is the spec.
2. **The backlog holds it.**

   ```bash
   RADIN_CLI scope --specs [<the same scope arg as Step 1>]
   ```

   It prints one `id`, `created`, `branch`, `commit`, `source`, `role`, `plan`,
   `facts` line per candidate, oldest first. `source` says how the entry joined: `commit` (the
   task's commit is in scope), `reflog` (a squash or rebase rewrote that
   commit, and the review branch's reflog still lists it), `patch` (a
   cherry-pick copied the commit under a new hash; the diffs, the author time and subject, or the subject alone, match) or `pending` (an
   open entry recorded on the review branch).

   - **Exit 4**: a recorded commit no longer exists and HEAD sits on no branch.
     Report the stderr line and stop the review.
   - **No output**: fall to rung 3.
   - **Lines**: take every line without asking.

   `plan` names the plan file(s), comma-separated. `facts` names the facts
   file. Add each path to the entry; `none` means absent. A `pending` id's
   task file resolves as in rung 1.

   `role` is `follow-up` or `feature`. Follow-ups are **decisions**; features
   are the **spec**.

   When every entry is a follow-up, there is no spec, only decisions, and
   Step 6 reports `no spec available`.
3. **Ask.** One `AskUserQuestion` offering the top entries from
   `RADIN_CLI backlog list` as options, with the free-text field carrying a
   path. "There isn't one" falls to rung 4.
4. **Skip.** No spec: say so once here, and report `no spec available` in
   Step 6.

## Step 3: Run the review

When the invoking prompt hands over a core review's findings for this scope,
skip the dispatch and relay those.

Dispatch one sub-agent (`name: "radin-review"`) with a self-contained brief:

- `Read RADIN_LIB/radin-review-core.md and follow it at level session` (level
  `diff` for a `staged` scope).
- The resolved scope line, Step 1's `command` string and commit list,
  verbatim.
- The spec and the decisions as absolute paths with "read it in full before
  reviewing". Label the decisions: "these entries fixed earlier findings on
  purpose; the scope's behaviour they describe is settled, so raise it again
  only when a changed line contradicts the decision."
- The skills Step 1's `passes` line names, as extra passes to invoke after
  the core's two.

Keep its report whole, in the order the sub-agent gave it. Step 4 carries it
to the user.

## Step 4: Filter, classify, triage

Nothing is logged or acted on until the user agrees to it. The citations go
through one filter, which drops the out-of-scope findings:

```bash
printf '%s\n' "<path:line per finding, one per line>" |
  RADIN_CLI scope --in-scope [<the same scope arg as Step 1>]
```

Keep the findings on the `in` lines, drop the `out` ones, and carry the
`dropped` count into Step 6. A finding about missing behaviour cites the
in-scope line the requirement should have landed on. A finding with no
in-scope line stays in Step 3's relay, and Step 6 names it as unlogged.

Classify each survivor: **fix** for incorrect behavior, including a missing,
partial or wrongly implemented requirement, and **refactor** for everything
else, scope creep included.

From shortcuts/radin, MIT.

More from shortcuts/radin