Files
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

4.7 KiB
Raw Permalink Blame History

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.