5090f1cf4e
Rewrite format.md around turn files, the output.md order (# outcome, edge word, # handoff, detail), checks, configs, human stages and the land stage delivery gate (sh -c in a fresh detached worktree, clean checkouts incl. untracked, 64 KB output cap, opencode only). Align review guidance across practices, verification, orchestration and the feedback-loop example. Fix loop-limit semantics in control.md against runner.go, budget_tokens sizing, read for large inputs, blocked-else-error and one stage naming set. Move dated verification logs to docs/verification-history.md and brokered chat, TUI keys and harness internals to docs/operator-reference.md; label operator-only references in SKILL.md.
89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
# Good practices
|
||
|
||
Pipelines are written by models through this skill, and a run's cost is roughly
|
||
model calls × context per call. Most waste comes from stages that re-read or
|
||
re-generate large output. `pipelines validate` enforces the mechanical rules
|
||
below (errors block publishing; warnings print and do not).
|
||
|
||
## Where work belongs
|
||
|
||
- **Deterministic checks belong in the server `checks` block, not the model.**
|
||
The `land` stage sets `delivery=true` and lists the full check commands; the
|
||
server runs them on the committed candidate (`references/format.md`, Delivery
|
||
gate). A model running the suite puts every log line into its context, and
|
||
every later call pays for it again.
|
||
- **`implement` runs focused tests only**: the test file or package it touched,
|
||
with quiet or summary output. Never the full suite.
|
||
- **`review` reads the changed hunks, not the repository.** Start from the
|
||
server-captured changed-file list the runner adds to the prompt and
|
||
`git diff --stat`, then read per-file diffs and only the code around them.
|
||
Review runs no suites; it judges the reported checks and names missing coverage.
|
||
- **`land` relies on server checks.** With a delivery gate its prompt commits and
|
||
stops; it does not re-run what the gate runs. Do not claim "the server lands
|
||
it" unless a stage has `delivery=true` (error otherwise).
|
||
- Every stage that can modify the workspace declares `checks`, even if only
|
||
`none: <reason>`. Checks must fail when a tool is missing: no `|| true`,
|
||
`[ ! -x tool ] || ...` or similar guards (error). Cover every language the run
|
||
can change.
|
||
|
||
## Prompts
|
||
|
||
- **Short stage prompts**: the goal and the real constraints. Over 2000 bytes
|
||
warns. Shared procedure belongs in project docs or this skill.
|
||
- **No runner boilerplate.** The runner already explains `output.md`, the
|
||
`# outcome` and `# handoff` sections, allowed outcomes, turn files, tools and
|
||
honesty rules. Repeating them warns.
|
||
- **Every outcome a prompt names is a declared edge.** "Return skipped" with no
|
||
`skipped` edge, or an undeclared `blocked_retryable`, fails the stage at run
|
||
time; validation rejects it (unquoted outcome words such as `skipped`,
|
||
`blocked`, `rejected`, `approved`, `advisory`; other back-quoted words after
|
||
return/report warn).
|
||
- **Missing tools or evidence**: declare `blocked` where a stage can lack required
|
||
input; the runner tells the model to choose `blocked` when declared, else
|
||
`error`.
|
||
|
||
## Memory and handoffs
|
||
|
||
- The runner inlines the essential `memory.md` into every prompt and asks each
|
||
stage for a short `# handoff` after its `# outcome` (`references/format.md`).
|
||
Do not repeat that instruction; say only what this stage's handoff must carry
|
||
if it is special.
|
||
- The full `history.md` and `input.md` are on demand for stages with `read`.
|
||
Never tell a stage to read the whole history every visit (warning); say when it
|
||
needs it, e.g. "read history.md only if the handoff lacks a detail you need".
|
||
- A stage without `read` gets `input.md` inlined (up to 32 KB) on every call. Give
|
||
`read` to any stage that follows a large output so it reads detail only when
|
||
needed.
|
||
|
||
## Loops and budgets
|
||
|
||
- **Loops get limits.** Put `{"max_visits":3,"on":["rejected"]}` on the reviewer;
|
||
leave the loop target unlimited or capped at least as high
|
||
(`references/control.md`).
|
||
- **Re-entry gets only findings**: a rejected review hands back must-fix items
|
||
with location and fix, and the implementer fixes those items rather than
|
||
redoing the task. Use `advisory` for non-blocking notes so they do not buy
|
||
another loop.
|
||
- **`budget_tokens` only when the user asks or a measured visit exists**
|
||
(`pipelines inspect RUN_ID --json`, `usage.tokens_total`). Size it 3–5× that
|
||
visit, remembering totals include cache reads, so a normal visit never trips it.
|
||
|
||
## Commands and scope
|
||
|
||
Every earlier tool result is re-sent on each later model call, so output a stage
|
||
reads once is paid for on every call after it.
|
||
|
||
- **Quiet commands**: use the project's quiet/summary test or analyze wrapper
|
||
(failures only plus a log path) and summary flags; never print generated or
|
||
vendored files.
|
||
- **Diffs**: `git diff --stat` or `--name-only` first, then `git diff -- <path>`
|
||
only for the files you need. Never a full diff or `git log -p`.
|
||
- **Files**: `grep`/`glob` first, then read only the relevant line range. Read a
|
||
whole file only when it is short or mostly being edited, and do not re-read a
|
||
file that has not changed.
|
||
- **Logs**: when a test log is needed, grep the log path for the failing test
|
||
instead of reading the log whole.
|
||
- **Batch independent tool calls** into one step instead of one call per step.
|
||
- **Small task scope**: one independently testable change per run (roughly a
|
||
10–15 minute change). Split larger work into several runs in parallel.
|