# 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: `. 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 -- ` 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.