kyleandClaude Opus 5.5
224617ee65
One list for the design model to work through per task, gathering the task-writing tips that apply before hand-over (T18, T19, T24 to T29, T32 to T35, T39, T40) and three new ones from the combined Ornith guidance: walk each given test by hand against the task's rules (T41), grep earlier given files for anything the task changes (T42), and run the gate's own checks on the given files (T43). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
# Before a plan is handed over
|
|
|
|
The design model works through this list for every task before a plan goes to the implementer.
|
|
Each item exists because of a recorded failure; the tip numbers point to
|
|
`docs/implementer-lessons.md`, and "Ornith guidance" to the combined assessment of three projects
|
|
(`~/projects/ornith/GUIDANCE.md`, section 5), whose crossbar findings are not in this repository's
|
|
log.
|
|
|
|
## The reference
|
|
|
|
- [ ] The reference is replayed through `make gate` at each task's end state, on the toolchain of
|
|
the host that will run the plan (T34), in a scratch worktree that builds into its own
|
|
`target/` (T35). If a worktree ever shared the main `target/`, run `cargo clean` in the main
|
|
tree before the run.
|
|
- [ ] The reference is broken on purpose one line at a time, and every break that can change
|
|
behaviour is caught by the given tests (T28). Record the count in the plan's README.
|
|
- [ ] Each task file is read against the reference for anything the reference has that the task
|
|
does not ask for (T26).
|
|
- [ ] The reference is moved off this machine (a git bundle on straylight) and its local branch
|
|
and worktree deleted before the run (T18).
|
|
|
|
## The given files
|
|
|
|
- [ ] Each given test fails against the tree before the task for exactly the reasons the task
|
|
names, and the task lists those tests by name.
|
|
- [ ] **Walk each given test by hand against the task's own rules.** A replay cannot catch a test
|
|
that no implementation following the task could pass (Ornith guidance: crossbar's pinned
|
|
event positions and tie-breaks).
|
|
- [ ] **Grep every earlier given file and fixture** for anything this task changes: strings,
|
|
JSON shapes, sentences, counts. A later task that changes a shared file gives the earlier
|
|
task its own copy (`name-taskNN`, T19; Ornith guidance: five breaks in crossbar).
|
|
- [ ] **Run the gate's own checks on the given files**: `cargo fmt --check`, the 500-line limit,
|
|
clippy on test targets. A given file that fails the gate stalls the run (Ornith guidance).
|
|
- [ ] No test depends on timing: every wait has a deadline on observable state (T27), no test
|
|
asserts the order of work done on separate threads (T32), and nothing sleeps instead of
|
|
waiting. Stress any test that ever flaked under load.
|
|
- [ ] No file the implementer reads holds the model's chat-template tags whole (T33): grep the
|
|
plan, the given files and the skeletons for them.
|
|
|
|
## The task text
|
|
|
|
- [ ] Every quoted "before" block is found exactly once in the tree at that task's start, and every
|
|
"after" block is in the reference.
|
|
- [ ] New code is a compiling skeleton; no `todo!()` has a comment longer than about six lines
|
|
(T25); every comment is read beside its signature (T29); conversions and accessors are
|
|
named (`u16::try_from`, `.get(i)`).
|
|
- [ ] A call table lists every API the task uses, with signatures (T25).
|
|
- [ ] Environment facts the implementer would otherwise go looking for are stated (OS limits,
|
|
library quirks, where a file lives). For a client of another program, its contract is
|
|
pasted in: a saved response or a schema fragment per call (Ornith guidance).
|
|
- [ ] The files section names the source directory of every copied file (T39).
|
|
- [ ] The steps give the gate's shell timeout, 600000 ms (T40), and `Cargo.lock` is in the
|
|
`git add` line (T24).
|
|
- [ ] The commit subject is given exactly. The trailer comes from `tools/run-plan.sh`.
|
|
- [ ] "Stop and report if" names the specific conditions: a quoted line not found, a different set
|
|
of failing tests, any other test failing, a comment that does not fit its signature.
|
|
|
|
## The run
|
|
|
|
- [ ] The plan README gives the command, with `OPENCODE_MODEL`, and the expected test count after
|
|
each task.
|
|
- [ ] The working tree is clean, the reference is off the machine, and the OpenCode TUI is closed.
|