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