Scribbles for my memory

Agent system prompts rot the same way every time: each fix tacks on a sentence, nothing ever comes off, and the prompt grows forever. Two things break as a result — the prompt drifts past whatever size budget you have, and (the subtle one) the prompt's prose is the agent's prose. A verbose, redundant constitution teaches a verbose, redundant writing voice.

So make every addition carry a matching subtraction. When you add a rule, find the existing rule it makes redundant and cut it. In practice the new rule almost always overlaps something — a preamble about "only ask when a decision genuinely needs the human" makes a stale "no confirmation requests for obvious next steps" bullet redundant; fold one into the other.

The part people skip: don't eyeball whether the wording "fits" — measure it. Render the prompt with all includes expanded, byte-count it, and compare against a budget:

# render each role's full prompt and check it against a per-role ceiling
for src in agents/*.md; do
  role=$(basename "$src" .md)
  _mat_render_prompt "$src" "/tmp/$role.md"
  size=$(wc -c < "/tmp/$role.md")
  ceiling=$(jq -r --arg r "$role" '.[$r]' ceilings.json)
  echo "$role: $size / $ceiling  (headroom $((ceiling-size)))"
done

A checked-in per-role ceiling turns this into a ratchet: adding a line either fits under existing headroom, or forces you to bump the ceiling in the same diff — which makes the growth visible and reviewable instead of silent.

Measuring mattered more than expected. The fattest candidate wording netted +161 bytes; the tightest role had exactly 163 bytes of headroom. Two bytes of slack — and a longer {{USERNAME}} at render time would have blown it. Invisible by eye, obvious once counted. We trimmed the wording to net +135 and left every ceiling untouched.

And run the ratchet both ways. When you remove fat, lower the ceiling to the new size × 1.10 in the same change — otherwise the slack you just created quietly refills.