| name | agent-prompt-doctrine |
| description | Eight falsifiable rules for prompting CLI coding agents and review lanes, each derived from an observed failing-form vs working-form pair. Use when composing any prompt for a coding agent or reviewer fanout. |
Agent Prompt Doctrine
Empirical origin: one day of orchestrated "review the whole package" fanouts burned >100M input tokens, produced four literal one-word REJECT verdicts, and shipped nothing. Weeks later, seventeen commit-sized one-shot prompts against the same codebase each ended "N passed" on a quarter of the tokens. The difference was never the model — it was the prompt shape.
The eight rules
- One prompt = one verifiable diff. Whole-package verdict requests get defensive rejections; "review ONLY these 3 files" / "make EXACTLY these changes" completes cleanly.
- Bound the evidence set. Inline the exact files/spec text the agent needs; lanes forced to re-read a whole repo burn tokens and return mush.
- Embed the acceptance command. Name the exact test command (with interpreter path) that must pass. "It should work" prompts end in the future tense.
- Enumerate prohibitions. Agents self-audit against explicit "do NOT reformat / do NOT add error handling / do NOT touch other files" lists. Unstated constraints get violated.
- Scope beats format-nagging. Scolding "give a terminal verdict, not one word" half-works; narrowing scope to one diff with evidence inlined actually fixes outcomes.
- No status protocols in one-shots. A "send WORKING before long passes" boilerplate caused lanes to END on the heartbeat — "WORKING: ..." as the final answer.
- Never respawn an unchanged fanout. Same prompt + same scope = same failure. Change the decomposition, not the dice.
- Pre-pay investigation. Implementer prompts contain conclusions (paths, line refs, decided approach), not open questions. Investigation is a separate, cheaper, read-only pass.
Prompt skeleton
<ONE commit-sized task statement>
Files: <exact paths, insertion points, line refs if known>
Spec: <verbatim spec text — do not paraphrase your plan>
Do NOT: <reformat / add defensive code / touch other files / run long test suites>
Must pass: <exact test command>
Timeouts
Full test suites hang agents (observed: a unit run stalled at 17% for 7+ minutes). Agents run focused test files only; the orchestrator runs the broad suite at the review gate.