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 answer a location question, run a PostGIS query, compare a fix against a gazetteer, or build a location visualisation → using-gps-data
• 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 notes through MCP patch/batch/put/reorder/table_op → MCP Note Editing Guide
• Starting work on a project → that project's note, located via CONTENTS
• Setting up or documenting infrastructure → README/lessons
• Starting a new session or task → README/agent (working practices: find before investigate, decisive action, targeted edits)
• Wondering how the notes server works, what port it uses, or where data lives → gdata-server/infrastructure
• Starting any session → read john/actions and mention any pending items to John, even if unrelated to the main task
• About to use tools, delegate to another agent, change external state, spend resources, alter infrastructure, or perform any privileged/high-impact action → AI Operational Safety Rules
• About to add a specific, checkable detail (a date, number, recent event, current condition) to round out an explanation, and haven't actually checked it → README/agent (“Don't pad an otherwise-correct answer with an invented specific”)
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.