Files
pipelines/internal/author/skill/references/practices.md
T
alan 5090f1cf4e Pipelines skill: outcome-first output, aligned review and loop guidance, operator material moved to docs
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.
2026-11-04 17:27:01 +00:00

89 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.