Agent Wranglers

Documentation Required

State each value in one document and link to it

Write each limit, time or threshold, such as a session length or a retry count, in one document only. Every other document links there.

How to do it

Pick the home by topic, such as security limits in the security guide. Elsewhere, write "within the session limit" with a link, never a second number. When you change a value, search all docs for the old number and the topic words first. Two documents that state different values for the same thing are a bug, because readers and agents apply whichever they find first. This follows keep each piece of knowledge in one place, applied to prose.

Example

# Each key topic should state its number in one file only
for topic in "idle timeout" "certificate.*days" "rotate.*days" "retries"; do
  echo "$topic: $(grep -rliE "$topic" docs/ | wc -l) files"
done

How to check

For each value in a list of key limits, a search of the docs finds one stated number. Every other mention is a link to that document.

Measured

On a reference site, a review of 17 guides written in parallel found 28 values or practices stated differently in two or more places.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/one-home-per-value.