build-reviewed

Files (1)

• SKILL.md

SKILL.md (first lines)

# A reviewed part: one critic, one fix round

A part of tier `reviewed` is a small code change with a fast gate: a script, a tool, a check, a
change to a test layout.
One builder builds the part. One fresh critic judges it blind, once. A new builder takes each later
round: a decided question, the fix and the finish. This session reads the result before the
finish.

**Run this in a session on the large model.** This session decides the questions inside the part
and reads the diff, so it is a reviewer, not only a dispatcher.

## 1 · Choose the part and check its spec

```bash
cd ~/Research && awk -f Harness/scripts/parts-table.awk "Tasks/<file>.md"
```

Take the part the user names, or the first part of tier `reviewed` that is `open`, has no unmerged
`blocked by` part, and collides with no part `in progress`. Check every `PR #NN in review` cell
with `gh pr view` first, as `build-part` says.

Read the part's sections and the file's §V and §L by line range. **The spec needs a *Done when*
whose clauses a command can check, and §V or §L must name the gate.** A part in `Packages/` or
`Experiments/` also needs *Decided at the edges* and *Tests catch*:
`python3 Harness/scripts/spec-gate.py "Tasks/<file>.md" <part>`. Write what is missing into the
section yourself, marked `(dispatcher, <date>)`, and commit the task file. An edge that changes a
public answer or picks between designs is the user's: ask, and go on with the next part.

**A part whose `sections` cell names `spec` has its spec in the spec-delta format**, and
`spec-gate.py` checks it wherever it lies. An `UNMEASURED` spec needs its device premises run from
a Kaimon session first, as `build-part`'s spec gate says. An `INVALID` spec does not start: set the state to
`waiting for the user — the spec fails spec-validate.py: <the first error line>`. For such a part,
write its bundle as `build-part` says, pass the bundle's path to every builder and the critic, and
write each decision and the loop's line into the spec's `## Decisions`, not the task file.

Set the state cell to `in progress`.

## 2 · Spawn the builder

Spawn `part-builder`; its frontmatter sets its tier. Pass the task file, the part, its
`PART` row and the `COLLISION` rows that name it, verbatim. Read `git remote get-url origin` first:
outside the user's own organisations, a push or a pull request needs the user's approval.

- **A part in `Packages/` or `Experiments/`**: `cd` into the repository as a Bash call of its own,
  then spawn with `isolation: "worktree"`.
- **A part that commits to `main`** (the plan's §L says so): spawn it in a worktree the same way,
  or without isolation from the repository, as §L says.

**Spawn a new `part-builder` for each later round; never `SendMessage` the last one.** A critic
takes 6–23 minutes, so a resumed builder finds its 5-minute cache expired and writes its whole
context again: 158–362 k tokens at each resume. A new one starts from the reports. First `cd` into
the builder's directory as a Bash call of its own, then the `Agent` call, without isolation. Pass
the task file, the part, its rows, the directory, the branch, the base, the head, the round, and the
last builder's report as the handoff note.

**A report whose *Question for the dispatcher* is not `none` holds the critic back.** Decide it from
the part's sections and the evidence, and write the decision into the section as
`**Decided (dispatcher, <date>):** <decision>`. Commit the task file, and spawn a new builder with
`Round: build`, the section and the line. Where the question changes a public answer, picks
between designs, or weakens the *Done when*, ask the user instead, and set the state to
`waiting for the user — <question>`.

A run under *Left for the dispatcher* goes to `julia-test-runner` (no `model` parameter), or you run
it yourself when it is short. Spawn a new builder with `Round: build`, the run's verdict line and
its failures.

## 3 · One critic

**A report with no *Mutants* table, or with an open survivor in it, is not ready.** The builder
writes and runs a mutant per guard, branch, comparison and decided edge of its change, and closes
or justifies each survivor. The fix round runs only the mutants that its fix touches (*A fix
round's mutants* in `~/.claude/skills/build-part/evidence.md`). **A report with no *Text checked*
table is not ready either**: as its last step of every round, the builder rereads each text line
that its diff adds, changes or makes false, and fixes the false ones. Spawn a new builder with
`Round: build` and that gap.

When the builder returns `ready for critic`, spawn **one** `part-critic`, without isolation. Pass the task file, the part, the builder's directory, the
base and the head. **Never pass the builder's report.** For a part whose gate runs longer than 5
minutes, spawn `julia-test-runner` on the head in the same message. **The gate of a spec-delta
part** adds the spec's checks after the gate, and CI on the pushed branch, as *The gate of a
spec-delta part* in `build-part` says; a failed check or CI job fails the gate.

The critic's report is finished when it holds `Verdict:` and its evidence table. Otherwise spawn a
new critic once.

## 4 · Read the verdict

- **PASS, and the gate green** — go to 5.
- **FAIL** — spawn a new builder with `Round: fix`, the critic's *Blocking defects* and *Other
  defects* verbatim, and the gate's failures. Add no instruction of your own; a decision goes into the
  section first, as in 2. When the builder returns `ready for review`, **check the fix yourself**:
  run each reproducer of the critic, run the gate, and read `git diff <judged head>..HEAD`. Each
  blocking defect is closed, and the fix diff adds nothing outside it.
  - All closed — go to 5.
  - **One is open, or the fix breaks a clause** — stop. Set the state to
    `waiting for the user — <the open defect>`, and report it with your recommendation: one more
    fix round, a change of design, a narrower clause, or the full loop of `build-part` from the
    base. No second critic runs without the user's decision.

**A blocking defect whose cause is the harness** — a tool, the environment, a moved `main` — is
not the part's. Repair it, and run the critic again.

## 5 · Your read, then the finish

Read `git diff <base>...HEAD` once against the *Done when* and the critic's evidence table. Your
read is the last check, not a second critic: a doubt you can show with a command goes to the
builder as a blocking defect, under 4. Then spawn a new builder with `Round: finish` and the
critic's verdict and evidence table. It finishes as the plan's §L says: a pull request in `Packages/` and `Experiments/`, else a push to
`main`. After a push to a repository with CI, background `gh run watch <id> --exit-status -R
<owner>/<repo>`.

Write the state cell from the builder's report, and add one line to the part's section:
`**The loop:**` the rounds, each decision, and each defect the critic found, with its class. For a
defect class that is not in `~/.claude/skills/build-part/edges.md`, add one line to that file's
source, `~/Research/Harness/skills/build-part/edges.md`.

## What this skill does not do

It does not merge, and it runs no advisor, no arbitrator and no second critic without the user.

From michakraus/ResearchHarness, MIT.

More from michakraus/ResearchHarness