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

81 lines
4.4 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 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.