Config hygiene

Read these first

• What belongs in a config file

What you will know

• Find a stale instruction in a config file and prove it is stale

  Compare the rule with current tool behavior, policy, or observed traces and preserve evidence that makes the rule invalid.

• Reproduce a case where a wrong instruction causes a worse outcome than omitting it

  A plausible false constraint can block valid recovery, whereas missing guidance may leave the agent an opportunity to choose safely.

• Establish a review cadence for standing instructions

  Assign ownership and review triggers such as model, tool, policy, or workflow changes so the file has an expiry mechanism.

• Show an agent confidently following an outdated rule

  Capture the input, injected configuration, trace, and output so the failure is attributable to the standing instruction rather than general model variance.

• Keep a config file short under pressure to add to it

  Set a token or line budget and remove duplicated, low-value, or better-encoded guidance before accepting a new rule.

Chapters

1. 1

   A false constraint removes the recovery path

   An instruction that was true once and is wrong now does more damage than no instruction at all, because it forecloses investigation. Told the internal search API has no pagination, the agent never reads the API surface, pulls fifty thousand records and blames the platform for the timeout. This chapter works through why prohibitions are the most dangerous stale entries: a stale permission gets corrected by a failing call, a stale ban is never tested.

   Read chapter
2. 2

   Proving a rule stale takes current evidence, not memory

   Suspecting that "deploys require a manual smoke test against staging" is out of date is not the same as showing it. Build the case from the running system instead: the pipeline definition where the smoke suite now fires automatically on promotion, the commit and date that changed it, and a replay in which following the rule literally produces a step that no longer exists. Asking colleagues whether they recognise a rule tests reputation, not truth.

   Read chapter
3. 3

   Attributing a bad outcome to one specific config line

   Teams dismiss agent failures as model variance, and a stale line hides comfortably inside that excuse. Breaking the tie needs four artefacts from one session: the request, the exact assembled configuration injected for it, the trace where the agent cites the rule, and the resulting action. Assembled into a chain they make the line the cause rather than a coincidence; missing any one of them and you are back to anecdote.

   Read chapter
4. 4

   The removal arm is what proves worse-than-nothing

   Chapter 1 argues that without the line the agent would have read the API surface and found the pagination parameters, and chapter 3 exhibits one run in which it cited the false line and failed. Neither of those is the comparison. Run the same task on the same commit with the line taken out, holding model, tools and prompt fixed, and read the two traces against each other — that pair is the only thing that turns "this line caused a bad outcome" into "this line is worse than no line". It is also what you hand someone who was not involved, since it does not ask them to accept your counterfactual on trust.

   Read chapter
5. 5

   Standing instructions expire when their subject changes

   Calendar-based review confirms signatures rather than facts, which is how an organisation reaches 100% audit compliance while three incidents trace to confidently wrong rules. Tie review instead to the events that invalidate guidance: schema migrations, tool upgrades, model swaps, policy revisions. Covers naming an owner, wiring the trigger into the change that fires it so an index migration also touches the config file, and what a trigger-based control still misses.

   Read chapter
6. 6

   Each new rule is paid for by removing an old one

   After an incident, three people want lines added to a file already at its 1,500-token budget. Work the triage: keep the invariant naming two services that must never share a database, refuse the paragraph about careful commit messages, push the retry policy down into the client or a skill where it can be executed rather than remembered. The budget only bites when adding is coupled to removing instead of to raising the cap.

   Read chapter
7. 7

   Deleting an unverifiable rule beats hedging it

   The asymmetry argument — a stale line costs tokens, a wrongly removed line costs an incident — is right about direction and wrong about magnitude. See where it genuinely holds, then the mechanism that defeats it, and why marking a doubtful entry "may be out of date" is worse than either choice: the false constraint stays in context and behaviour becomes inconsistent rather than predictably wrong. Ends with a rule safe to hand someone who will apply it literally.

   Read chapter