For any agent working against this notes system — Claude, Codex, Envoy, or future tools. Its job is to make rule-reading mechanical rather than discretionary: you match what you are about to do against the map below and read the named note(s) before acting.
Reading rules on demand is fine — you need not read every rule upfront. But the moment you recognise you are entering a governed area (writing or editing code; creating or editing notes; changing infrastructure), stop and read the mapped note(s) before you act in that area, even if you are already mid-task.
Re-reading mid-task is expected and correct. Discovering relevance late is normal. The failure mode is pressing on once relevance has become clear — not the fact that you began before reading. If you realise halfway through a task that a note governs what you are doing, the right move is to stop and read it then, not to reason that it is too late to matter.
Cadence is currently freeform: act on the trigger whenever you recognise it, with no fixed checkpoints. (This is a deliberate first attempt — see gdata-server/todo for the August re-evaluation of whether fixed checkpoints work better.)
• About to write or edit code → ai-agent-guidelines and philosophy
• About to catch or suppress an exception → exceptions
• About to write a CLI entry point or script-cum-library → main-pattern and error-messages
• About to create or restructure notes → README/workflow and README/orphaning
• About to edit note blocks (patch/batch) → read-before-write: fetch with include_block_ids, use if_rev. See ai-agent-guidelines rule 5.
• Starting work on a project → that project's note, located via CONTENTS
• Setting up or documenting infrastructure → README/lessons
When a new rule note is created that should fire on a recognisable situation, add a line to the map. The map is only useful if it stays current — an unlisted rule is a rule that will not be read on time.