81 lines
4.4 KiB
Markdown
81 lines
4.4 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 landing stage sets `delivery=true` and lists the full check commands; the
|
||
server runs them on the committed candidate. A model running the suite puts
|
||
every log line into its context, and every later call pays for it again.
|
||
- **Code runs focused tests only**: the test file or package it touched, with
|
||
quiet or summary output. Never the full suite.
|
||
- **Review reads the diff, not the repository.** Start from the server-captured
|
||
changed-file list the runner adds to the prompt and `git diff --stat`, then read
|
||
only the changed hunks and the code around them. Review runs no suites; it judges
|
||
the reported checks and names missing coverage.
|
||
- **Land/committer 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>` (`references/format.md`, Checks). 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 (`internal/stage/model_prompt.go`). 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).
|
||
|
||
## Memory and handoffs
|
||
|
||
- The runner inlines the **essential memory** (`memory.md`: task, previous
|
||
stage's handoff, outcome ledger, changed files; capped) into every prompt, and
|
||
asks each stage to start its output with a short `# handoff`: what it did,
|
||
outcome, files changed, open findings, in a few lines. Do not repeat that
|
||
instruction; say only what this stage's handoff must carry if it is special.
|
||
- The **full history** (`history.md`) and full `input.md` are on demand. 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".
|
||
|
||
## Loops and budgets
|
||
|
||
- **Loops get limits.** An edge back to the same or an earlier stage needs
|
||
`limits` on the source outcome or the target (error). Use `max_visits` 2–3.
|
||
- **Re-entry gets only findings**: a rejected review hands back must-fix items
|
||
with location and fix, not a full re-review, and the implementer fixes those
|
||
items rather than redoing the task. Use `advisory` for non-blocking notes so
|
||
they do not buy another loop.
|
||
- Set **per-stage `budget_tokens`** (and `budget_usd` if wanted) as a runaway
|
||
guard on stages that loop or explore, sized a few times a normal visit.
|
||
|
||
## 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.
|