Files
pipelines/internal/author/skill/references/practices.md
T

4.4 KiB
Raw 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 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.