Prompt Writing

Default to principles. Escalate to procedures when you observe agents deriving the wrong sequence from the principle. If the same misordering recurs after one rewrite of the principle, the ordering is inherently non-obvious — encode it as a procedure.

Direct statement

Agent and Bash: always `run_in_background: true`. Never call TaskOutput to block — completion notifications arrive automatically.

One sentence per rule. If it needs two, the second closes a loophole or names the mechanism.

Procedure (when ordering matters)

1. Run tests  2. Read output  3. Only then commit

Use only when misordering causes real harm.

Socratic question (context-dependent)

Before abstracting: can I point to two call sites that need this? If not, inline it.

Encodes the principle AND the edge cases. The agent reasons about its current context rather than pattern-matching a static rule. Use when the correct behavior depends on circumstances.

Before writing, ask:

• Adversarial reading test: Read the rule as a literal-minded agent would. If the text permits a behavior that violates your intent, it will happen. Tighten until literal and intended readings converge.
• Single concern: Does this rule bundle two concerns? Split them. Agents follow atomic rules better than compound ones.
• Motivation check: Am I explaining why? Cut it unless the why prevents misapplication. Agents need compliance targets, not motivation.
• Identifier over description: Can I use an exact identifier (run_in_background: true) instead of a description ("run things in the background")? Identifiers are unambiguous and usually shorter.
• Is this a principle or a procedure? If the agent needs to reason about context, encode as a Socratic question. If it just needs to do the thing, direct statement.