build-part

Files (3)

• SKILL.md
• edges.md
• evidence.md

SKILL.md (first lines)

# Running a part through the builder-critic loop

A parts table lists the parts of a plan. This skill starts each available part in the
**builder-critic loop**: a specialist builder makes the work, and a separate critic with a fresh
context judges it blind against the part's benchmark. The loop repeats until a critic passes the
work.

**The `model: medium` of this skill does not apply**, typed as `/build-part` or invoked through
the Skill tool: the turn stays on the session's model. Dispatching is table reading, and it is not worth an opus turn: run
the loop in a session on sonnet. **When this session runs on another model, say so to the user in
one line before the first spawn**, and go on.

**Spawn `julia-test-runner` without a `model` parameter.** A `model` passed to the `Agent` tool
replaces the agent's own, so a runner spawned with `model: opus` runs on Opus, not on Haiku.

**Contents**

- [Never read the task file](#never-read-the-task-file)
- [Choose the part](#choose-the-part)
- [The tier cell decides whether the loop starts now](#the-tier-cell-decides-whether-the-loop-starts-now)
- [The spec gate](#the-spec-gate)
- [The loop](#the-loop)
- [A question inside the loop goes to the advisor](#a-question-inside-the-loop-goes-to-the-advisor)
- [Hold the state cell yourself](#hold-the-state-cell-yourself)
- [Several parts at once](#several-parts-at-once)
- [Stop, and say why](#stop-and-say-why)
- [What this skill does not do](#what-this-skill-does-not-do)

## Never read the task file

Run the extractor. The largest task file is about 33 000 tokens; this output is about 200.

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

```
PART       part  repository  sections  tier  state
COLLISION  repository  file  parts
```

Empty output means the file carries no parts table. Say so, and offer the `plan-parts`
skill. Do not decompose it here.

**Every builder and critic reads the part's spec bundle, not the task file.** Write it with
`spec-bundle.py`, which copies the part's rows, its sections, §V, §L and every section that §L's
*also reads* lines name into one file:

```bash
cd ~/Research && python3 Harness/scripts/spec-bundle.py "Tasks/<file>.md" <part> --out ~/Research/.scratch/spec-bundles/<file>/<part>.md
```

It prints the path, the line count and the body's hash, and one `unresolved: <name>` line on
stderr for each name of the cell or of §L that matches no heading and no table row; then it exits 1.
**Write the bundle again before every spawn of a builder or a critic**, so that a decision written
into the task file since the last spawn is in it. Pass its path on the spawn.

**A part whose `sections` cell names `spec` has its spec in the spec-delta format**, at
`Tasks/Evidence/<file>/<part>/spec.md`, and the bundle holds it whole. For such a part, *the part's
section* in this skill is that spec's `## Decisions`, below its four sections: write every decision
and the loop's record there, and commit it with the task file. The state cell stays in the task
file. Its gate adds the spec's checks and CI (*The gate of a spec-delta part*, in the loop).

## Choose the part

**Check every cell that names a pull request against GitHub first.** The user merges in silence,
so a `PR #NN in review` cell can be stale for days, and every part `blocked by` it reads as blocked.
For each such cell, run `gh pr view <NN> -R <owner>/<repo> --json state,mergedAt` as a Bash call of
its own, with the repository from the part's `git remote get-url origin`. Write a merged one as
`merged — PR #NN, <date>`, and a closed one as `declined — PR #NN closed`. Then a `blocked by` cell
whose parts have all merged becomes `open — <part> merged`. Commit the task file before you go on.

Where the user names a part, use it. Otherwise take the first part that passes all three:

1. the state is `open`;
2. no `blocked by` part of it is still unmerged;
3. its files collide with no part you are about to start, and with none that is `in progress`.

`state` is one of `open · in progress · waiting for the user · PR #NN in review · merged ·
declined`. Anything else is prose that a person wrote — read it, and treat an unclear state as *not
available*. A part `waiting for the user` is not available until the user writes its decision.

## The tier cell decides whether the loop starts now

| `tier` cell | do |
|:--|:--|
| `build` | start the loop, once the part passes the spec gate below |
| `reviewed` | not this loop: the `build-reviewed` skill builds it, with one builder and one critic |
| `direct` | not a loop: the main session makes the change, or a workflow for a change across many repositories, and checks it with the commands of its *Done when*. Report the part |
| `decision` | **do not start it unprompted.** Report the part: it holds a decision. Start the loop when the user names the part and says its decisions are recorded |
| empty, or anything else | treat as `decision`, and name the cell so the user can fix it |

**The roles have fixed tiers.** The builder is `julia-builder` at `opus-medium`; every critic is
`julia-critic`, at `opus-high` in round 1 and at `opus-medium` in a verify round; the advisor is
`advisor` and the arbitrator is `arbitrator`, both at `opus-high`. Their frontmatter sets the
effort, except for a round-1 critic: its `Agent` call passes `effort: "high"` over the frontmatter's
`medium`. Pass `model: opus` on every spawn of these four, and never spawn one of them on sonnet or
haiku.

**A decision part is the user's.** Name the part, its repository and its `Done when`, and say it
waits for the user's decisions. Where its section holds no recommendation yet, spawn the `advisor`
once with the part's open questions, and write its answer into the section as
`**Recommendation (advisor, <date>):** <decision>` — the user then decides with the work done.

Then carry on to the next available part. Reporting a decision part is not a reason to stop; only
**substituting** one part for another in silence is. Your report names every part you started, and
every part you did not, with the reason.

## The spec gate

A `build` part in `Packages/` or `Experiments/` starts only when its sections hold a
`**Decided at the edges**` and a `**Tests catch**`. Run the check for the part:

```bash
cd ~/Research && python3 Harness/scripts/spec-gate.py "Tasks/<file>.md" <part>
```

It prints `PASS`, `EXEMPT`, `MISSING <labels>`, `INVALID <n> errors`, `UNMEASURED <devices>` or
`SPANS <repositories>`, and exits 0, 0, 1, 1, 2 or 1. **`UNMEASURED` is no pass**: a premise needs a

From michakraus/ResearchHarness, MIT.

More from michakraus/ResearchHarness