plan-parts

Files (4)

• SKILL.md
• plan-sections.md
• premise-check.md
• spec-format.md

SKILL.md (first lines)

# Planning parts for the builder-critic loop

A **part** is one pull request. One branch, one worktree, one *Done when*. The parts table is the
plan's machine-readable half: a later session reads one row and builds it without reading the rest
of the file. Each part's own section is its **spec**: what the builder builds to and what the
critic judges against, blind.

Two entry paths, same output.

| path | you have | do |
|:--|:--|:--|
| **forward** | a discussion, no file yet | write the table and the specs as the plan forms, not after |
| **backward** | a finished task file | read it, add the table, the specs, §V and §L, change nothing else |

**Contents**

- [1 · A part is one pull request](#1--a-part-is-one-pull-request)
- [2 · The parts table, first section after the done-condition](#2--the-parts-table-first-section-after-the-done-condition)
- [3 · The collision map, before the split is fixed](#3--the-collision-map-before-the-split-is-fixed)
- [4 · A tier cell per part, from a stated reason](#4--a-tier-cell-per-part-from-a-stated-reason)
- [5 · What must not be split](#5--what-must-not-be-split)
- [6 · Each part's section is its spec](#6--each-parts-section-is-its-spec)
- [7 · The plan's §V and §L hold only what the plan adds](#7--the-plans-v-and-l-hold-only-what-the-plan-adds)
- [What this skill does not do](#what-this-skill-does-not-do)
- [Run this on the capable model](#run-this-on-the-capable-model)
- [Grading a table you produced](#grading-a-table-you-produced)

## 1 · A part is one pull request

One sentence describes it. A part that needs two sentences is two parts.

The test is the reviewer: **a part is right-sized when one person can review its diff in one
sitting and say yes or no.** Not "how long will this take" — a mechanical rename across forty files
is one part; two design decisions in one file are two.

**One part per finding is not a decomposition.** Group by theme — what a reviewer judges together —
not by numbered item. Findings that share a cause, a file set or a kind of fix belong in one part.

> **The check: if your part count is within two of your finding count, start again.** Twenty
> findings become about seven parts, not eighteen. Over-fragmentation is the common failure and it
> is worse than a part that is slightly too large: every extra part is another branch, another pull
> request, another review, and another row in the collision map.

**A part that changes ten or more source files (`src/`, `ext/`), or four or more kinds of work,
is two parts.** The kinds are source, tests, docs, scripts, CI and the project files; `CHANGELOG.md`
and `KNOWN_ISSUES.md` do not count. In the production loops such a part takes a median of three
critic rounds and a builder context near 480 k tokens, against one round and about 100 k for a part
of three source files or fewer. Split it where a reviewer judges apart: the interface, the
algorithm behind it, the migration of its callers. A mechanical change is exempt, as above.

**Do not split one part into steps with a critic loop each.** Each step pays a full loop, and no
critic judges the part as a whole.

**The exception is a change too wide to land green at once.** A rename or a signature change whose
blast radius reaches thousands of call sites breaks the suite the moment it starts, so no single
part can both make the change and pass CI. Sequence it as **expand → migrate → contract**:

| step | the part | state |
|:--|:--|:--|
| **expand** | add the new form beside the old one. Nothing breaks | open |
| **migrate** | move the call sites over in batches sized by repository or directory, one part each | `blocked by` the expand |
| **contract** | delete the old form once no caller remains | `blocked by` every migrate part |

Each migrate part stays green on its own, because the old form still exists. Where even a batch
cannot stay green alone, keep the sequence and give the batches a shared integration branch that a
final verify part is `blocked by`; green is promised there and nowhere earlier.

## 2 · The parts table, first section after the done-condition

```markdown
## Parts

A session given a part reads its spec bundle: the part's rows, its sections, §V, §L, and the
sections that §L names. It does not read the whole file.

| part | repository | sections | what it is | tier | state |
|:--|:--|:--|:--|:--|:--|
| **A** | `Example` | §1–§4, §V, §L | Wrong answers and unreachable API. No design decision. | build | open |
| **B** | `Example` | §5–§7, §V, §L | What `periodicity` returns. Changes the public answer. | decision | open |
| **C** | `ExampleTools` | §11, §V, §L | The accessor loops. Mechanical. | build | blocked by B |
| **D** | `Example` | spec, §V, §L | The new solver option. A spec in the spec-delta format. | build | open |
```

`state` is one of `open · in progress · waiting for the user · PR #NN in review · merged ·
declined`.

**Every `sections` cell ends in `§V, §L`.** The builder and the critic of a part read only the
spec bundle that `spec-bundle.py` writes from the task file: the sections a cell names, §V, §L,
and the sections that §L's lines **The builder also reads:** and **The critic also reads:** name.
A rule in any other section does not reach them. So a decision block of a parent part, a *Traps*
section and the plan's working rules reach a part only through its cell or through those two
lines. Name each one in a form the script resolves: a key (`§6`, `§5V.P38`), a heading in italics
(`*Traps*`), or `the preamble of §<key>`. A phrase that starts with "the part's" or "its" points
back to the cell and adds nothing. Give the builder and the critic the same sections, unless a
section is only a judging aid. The key `spec` names the part's spec in the spec-delta format
(§6).

**Write the bundle of each part before the plan is done**, and read its header:

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

Every `unresolved:` line is a defect of the plan: fix the cell or the §L line. The header's list
of sections is what the builder will read; a section the part needs and the list lacks is the
same defect.

**The table does not replace the checkboxes.** Checkboxes record findings; the table records units
of work. A file carries both.

## 3 · The collision map, before the split is fixed

List which files each part touches. Two parts that share a file **cannot be built in parallel**,
whatever they cost to run.

```markdown
### File collisions

| file | parts |

From michakraus/ResearchHarness, MIT.

More from michakraus/ResearchHarness