system-prompt

Capability: system prompt

This capability treats one or more prompt/policy text files (prompt.txt, policy.md, SYSTEM.md) as the optimizable artifact — whatever text the runtime prepends to the agent's context as its instructions, output contract, and decision policy.

Prose is the right lever when the agent lacks something it could be told: a format, a rule, a decision criterion. It is the wrong lever when the agent already has the rule and does not act on it — that needs the behavior enforced in code, so it belongs to whatever capability edits the agent's tools, not here. Classify the failure clusters first (./guidance/diagnose/SKILL.md, when present) and spend prose only on the clusters this capability can actually move.

Pick the lever

Each item is a bounded edit class. Fix the biggest cluster with the narrowest lever that reaches it; ship every class the traces call for in one candidate. Examples are 1-line and generic; depth is in references/concepts.md.

1. Rewrite a rule for clarity, positively framed — say what TO do, specifically. A prohibition fences off one wrong path; a positive instruction names the target. Ex: "Don't be vague" → "State the record ID in every reply."
2. Add the reason to a bare rule — a rule paired with its rationale extends to cases the rule's author never wrote down; a bare imperative does not. Ex: "Never use ellipses" → "Never use ellipses — the output is read by a TTS engine that cannot pronounce them."
3. Consolidate redundant rules — merge duplicates into one, keeping every distinct constraint. Ex: three "confirm before deleting" lines → one "Confirm before any destructive action (delete, overwrite, send)."
4. Add a rule the source requires but the prompt omits — it must trace to a real source (the policy doc, the runner, the task spec), never be invented. The added rule may introduce a constraint the prompt lacked, or state a stricter condition on an existing one. It may not broaden an existing permission or flip a decision the agent currently gets right: that changes behavior for every task in the class, including the passing ones whose gold answer was the stricter behavior. When a cluster needs different behavior, name the exact condition that separates the qualifying cases instead. Ex: the source says refunds need a manager code → "Require a manager code before any refund."
5. Add an example — one or a few <example>-tagged exemplars to pin a format that is hard to describe in prose. Ex: one <example> showing the exact JSON envelope expected. Examples are re-read every turn, so add the smallest set that pins the shape and treat a larger set as a hypothesis to gate, not a free win.
6. Restructure — separate instructions, context, examples, and input into their own sections or tags so the model does not conflate them, and put long reference data before the instruction that acts on it.
7. Add a role / goal line — one sentence on who the agent is and what "done" means, when the prompt has none. Ex: "You are a careful support agent; resolve the request in one turn."
8. Tighten the output contract — make the required shape explicit and exact. Ex: "Reply with only a JSON object {status, reason} — no prose." If the scorer reads the agent's final message, the contract must require the agent to state every value the scorer checks: agents routinely perform the action correctly and never report the result, and the scorer sees only the omission. (A missing action, as opposed to a missing report of it, is not fixable here — see the scope note above.)
9. Soften over-strong wording — when a cluster shows the agent over-doing rather than under-doing (excess tool calls, over-engineering, triggering a behavior where it did not apply), downgrade CRITICAL/MUST/ALWAYS to "Use … when …". The edit that fixes an over-eagerness cluster is a cut, not an addition.