review-triage

Files (1)

• SKILL.md

SKILL.md (first lines)

# Review triage

You are classifying, not judging. Whether the change is correct is the
`correctness` check's question and it is already dispatched. Yours is narrower:
**which specialist checks does this diff warrant?** The usual honest answer is
none.

## What it reads

Three inputs, in this order.

1. **The check index** — the pack's checks, with the rows of the
   `review-checks.toml` the commit under review carries laid over them. It
   declares the checks you may add. Read it first; it is the one place the
   available checks are declared.
2. **The anchor** — `<anchor_bead>`, which states what the change was for, and
   the rig's guidance for triage, the reviewed commit's `docs/review-triage.md`,
   which the review formula printed when the commit carries one. A rig steers
   triage there in words, such as never adding a check, or adding one only for
   one kind of change: advice you weigh beside your own reading of the diff.
3. **The diff, at the reviewed commit** — in `<worktree>`,
   `git diff --stat origin/<review_base>...HEAD` first, then a skim of the
   files the stat names. A skim is the method here; reading every hunk is the
   specialist reviewer's job, not yours.

### The index

Read the index through the pack's resolver rather than eyeballing a file. It
has two layers. The pack's own index declares every check the pack ships a
skill for, so every rig has them. The reviewed repo's `review-checks.toml` at
the commit under review, when it keeps one, adds checks of the rig's own and
can change a pack check's purpose or phase for that rig. The resolver is the
pack's own copy, which `gc <binding> scripts-dir` finds from any rig: it prints
the directory holding the pack's scripts. `<binding>` is the name the city
imports the pack under, which gc puts in front of this skill's name:
`gc-toolkit` in `gc-toolkit.review-triage`. `gc skill list` prints it in this
skill's FROM column. The rig's rows come out of `<reviewed_oid>`, not off disk —
the tree you stand in is your own worktree, not the commit you are classifying,
and a branch may change the index it is judged against:

```bash
# >>> triage-index-read
"$(gc <binding> scripts-dir)/review-checks.sh" --show --at "<reviewed_oid>"
# <<< triage-index-read
```

Each row gives you the check, one line of purpose, and its phase — the stage
transition by which it must read green. When a check applies is a judgment its
method states, so read the method: the skill `<binding>.review-<check>` in your
catalog. A check of the rig's own has no skill, and its purpose is the whole of
what it judges. The phase is fixed per check and not triage's to choose, and
there is no applies-when column in the index.

A commit that carries no index of its own still has the pack's checks, so
every review has a menu. A non-zero exit is an index nobody read: a commit the
checkout cannot read, a reviewed commit the block was not given, or a scripts
dir gc cannot print. Stop and say so rather than classify with no menu. A row
the resolver refuses, a phase outside the ordered set, is left off the menu and
named on stderr. That row is the index gap.

### The index gap

A rig row the resolver refuses is your first finding. File it as an
observation and classify over the rows the menu shows. Filing is recording,
not proposing: the distiller judges it and a reviewed PR writes the index.

```bash
# >>> triage-index-gap
OBS_META=$(jq -nc --arg scope "repo:${GC_RIG:-unknown}" --arg prov "bead:<anchor_bead>:turn:$(date -u +%Y-%m-%d)" \
  '{task_kind: "observation", "obs.category": "review-index-gap", "obs.scope": $scope,
    "obs.source": "self", "obs.directive": "standing", "obs.provenance": $prov,
    "gc.outcome": "recorded", "gc.work_outcome": "no-op"}')
OBS_JSON=$(gc bd create "obs: check index row refused (bead:<anchor_bead>)" \
  -t task -l learning -l observation --metadata "$OBS_META" --status=closed -d "## Statement
<the row the resolver refused, and why>

## Quote
Triage on <anchor_bead> at <reviewed_oid>.

## Proposed norm
<draft — explicitly non-binding>" --json)
OBS=$(printf '%s' "$OBS_JSON" | jq -r 'if type == "array" then (.[0].id // empty) else (.id // empty) end' 2>/dev/null)
[ -n "$OBS" ] || { CREATE_ERR=$(printf '%s' "$OBS_JSON" | jq -r 'if type == "object" then (.error // empty) else empty end' 2>/dev/null); echo "observation not filed${CREATE_ERR:+: $CREATE_ERR}" >&2; exit 1; }
# <<< triage-index-gap
```

### A bring-current round that conflicted

Bringing the branch current means merging its base in. When that took
resolution by hand, the worker wrote one audit entry per conflicted file and
per edit beyond the merge, `bring-current-guard.sh` stored the entries on the
anchor beside its own diff evidence, and it reopened this lane. So the anchor's
`bring_current_record` holds a conflicted round with no `triage` ruling, the
reason the review formula prints says so, and your verdict also rules on that
round. `signoff.sh` refuses the verdict without the ruling.

Read the round first:

```bash
# >>> triage-round-read
"$(gc <binding> scripts-dir)/bring-current-audit.sh" render --anchor "<anchor_bead>" --as comment   # the account
"$(gc <binding> scripts-dir)/bring-current-audit.sh" show --anchor "<anchor_bead>"                  # the raw record
# <<< triage-round-read
```

The account gives a routine entry one line. The raw record keeps what that
line leaves out: what collided, what to check, and git's evidence.

## What it judges

The check index is closed: you may add any check it declares and you may not
invent one. For each check the index declares, read its method and ask whether
the diff you skimmed warrants it. Add the check when the answer is yes. Two
rules bound the judgment:

- **A check's method may name paths that make it mandatory.** When the diff
  touches such a path, the check is added whatever the rest of the method would
  argue. Nothing re-derives the diff behind you, so a miss here is a check the
  anchor never gets.

From zookanalytics/gc-toolkit, MIT.

More from zookanalytics/gc-toolkit