Document every agent with five components

When This Fires

• When installing any new behavioral agent — document before or during installation, not after
• During agent portfolio reviews when you need to assess what's active and what's degraded
• When diagnosing a failing agent (Diagnose before redesigning — identify whether trigger…) — you need the documentation to know what was supposed to happen
• When sharing behavioral systems with others (coaching, teaching, team practices)

Common Failure Mode

Documenting agents mentally: "I know what the trigger is." After a month, you don't — you remember a vague version that's drifted from the original design. The documentation isn't for your current self; it's for your future self who has forgotten the design details, and for your debugging self who needs the specification to diagnose failures.

The Protocol

(1) For every agent you install, create a written record with five fields: Name: a descriptive label (e.g., "Morning Writing Agent"). Trigger: the observable event that initiates it (Agent triggers must be observable or measurable — vague…). Conditions: when it fires vs. doesn't (including "always" if no conditions — Write all three components of default agents — even…). Actions: specific, ordered steps (Write agent actions as procedures a stranger could follow…). Success criteria: measurable outcome and minimum firing rate (Define agent success as 80%+ firing rate, not subjective…). (2) Store in an accessible location — notebook, app, or knowledge system. (3) Reference during reviews: is the documented specification still matching actual behavior? If not, either the agent has drifted or the documentation needs updating. (4) Update documentation when you modify any component — stale documentation is worse than none because it generates false confidence.