How to work effectively with this notes system. Written from direct feedback — lessons from actual sessions.
When you find yourself running exploratory commands to understand infrastructure, server setup, port numbers, or configuration: STOP. Read notes first.
CONTENTS → project page → relevant sub-note. Infrastructure is documented in memory/envoy/infrastructure and gdata-server/infrastructure. Config is in john/system-config. If the note exists, reading it takes 2 seconds; rediscovering the same fact takes 10 minutes.
The pattern that cost time: investigating where the GDBM file was, what port the notes server uses, whether the server is local or remote — all of this is documented. The failure was not checking notes first.
When you figure out something non-obvious during a session, write it into the appropriate note before moving on. Don't rely on being able to reconstruct it next session from the code or git history.
Document manual steps explicitly. If an operation is not automated by code or a reusable procedure, say what was done and what should be done next; otherwise the step leaves no durable record.
Specifically: infrastructure facts, troubleshooting procedures, anything you had to investigate rather than read.
When you know what to do, do it. Don't analyse alternatives you won't take.
Examples of what worked well:
• Document was corrupt JSON — wrote a correct replacement from scratch and PUT it, rather than trying to repair the corrupt string.
• 8 notes needed 'noodle' → 'gravlax' — wrote a script to do it programmatically in one pass.
These were both faster and cleaner than the investigative alternative.
Prefer patch / batch for targeted edits when the block-level change is straightforward. Always fetch with include_block_ids=true before patching so you have current block IDs and rev. Use if_rev when available.
For structural note edits, read MCP Note Editing Guide and use whole-document put when it is easier to inspect and safer than many positional operations.
Recovery discipline for positional edits (from repeated slips 2026-07-22): (1) before any insert_after/insert_before/replace_block, run outline and target the block off that — never off an earlier get whose block list you've mentally indexed, since eyeball-counting opaque IDs against content is where mis-anchoring happens. (2) When an edit lands in the wrong place, prefer the cheap correction — a reorder (e.g. to undo the reverse-ordering of multiple same-anchor insert_after ops), or a single follow-up patch to move/replace the one block. Escalating to a whole-document put to fix a one-block slip is wasteful and adds fresh transcription risk; reserve put for genuinely structural rewrites.
When creating a note, ask: what will I be doing when I need this? Name and place the note accordingly.
• Infrastructure facts → memory/envoy/infrastructure or gdata-server/infrastructure
• Troubleshooting procedures → <project>/troubleshooting
• Working rules → README/agent (this note) or PROGRAMMING_RULES/*
• Triggers for when to read which note → TRIGGERS
Add every new note to CONTENTS and to TRIGGERS if it governs a recognisable situation.
Before creating a new convention note or adding a rule to MEMORY/TRIGGERS, identify the concrete mechanism that will keep it current: who writes it, when, and triggered by what. If no reliable mechanism exists yet, record the idea in a proposal or the relevant todo instead. A convention with no maintenance path becomes stale misinformation faster than no convention at all.
1. Read TRIGGERS — check if the task enters a governed area.
2. Read the project note via CONTENTS to understand current state.
3. For envoy work: notes read memory/envoy first.
4. Check CONTENTS for any adjacent note that's relevant before assuming you need to investigate.
When asked to enumerate, list, or describe what exists — tools, files, options, capabilities — actually check rather than reporting from memory or current context. What is visible in the current context may be a subset of what exists. Use the appropriate lookup (tool_search, notes read, ls, etc.) before stating the answer.
When someone expresses surprise or scepticism at an answer, treat that as a strong signal to re-check immediately — not to restate the same answer with more confidence. The disbelief is evidence. Check before responding further.
The failure mode: asserting a fact confidently from partial information, then when challenged, explaining the partial information more thoroughly instead of verifying it.
Caught in practice 2026-07-22: inferred a DLR boarding point from a single nearest-fix match (South Quay), stated it confidently, and only found the actual boarding station (Heron Quays, one stop earlier) once the person pushed back. The dwell signature that gave the right answer — multiple consecutive near-zero-movement fixes near a station — was available in the data the whole time; it just wasn't checked before the first answer was given. Documented as a general method in using-gps-data (“Inferring boarding/alighting points”) so the check happens before answering next time, not only after being doubted.
Don't pad an otherwise-correct answer with an invented specific. Caught 2026-08-05: when explaining that two docks would share water temperature, added the qualifier "especially with no recent hot spell" — a specific, checkable claim about recent weather that was never actually checked, just plausible-sounding filler to make the explanation feel more complete. It was wrong: 2026 has had record-breaking heat since spring. The person's point: this is the dangerous case, not the safe one — an implausible fabrication gets caught, but a plausible one is invisible to the person unless they happen to already know the answer. If a claim would be easy to check (weather, current events, prices, current status of anything) and a search tool is available, either check it before including it or leave it out — don't reach for a detail that merely sounds reasonable to round out an explanation.
When the conversation begins with a compaction notice (the system tells you the conversation was summarised to free context), treat any claims in that summary about prior work, decisions, or state as potentially incomplete or misrepresented. The summary was generated automatically under token pressure and may have missed nuance, got ordering wrong, or omitted the fact that something was in progress rather than complete.
Concrete steps: (1) re-read the relevant notes directly rather than trusting the summary's account of them; (2) check the transcript if something seems off; (3) before implementing or acting on anything the summary says was decided or agreed, verify it is actually in the notes. The summary is a starting point for orientation, not a source of truth.
When preparing text for a Jira text-input field, return the literal Jira markup inside a fenced text block so the chat renderer cannot convert it. Jira bullet lines must begin with * . Do not substitute Markdown - bullets. Jira headings use h1. through h6.; choose the level appropriate to the document structure and omit headings only when the target field does not need one. Keep labels and explanatory prose outside the copyable block, and do not place Markdown fences or other chat-only formatting inside the Jira payload.
Trigger: whenever the user says “Jira style”, “Jira markup”, “text input”, or asks for text to paste into Jira, optimize for literal copy-and-paste output rather than attractive rendering in chat. If corrected on formatting, reissue only the corrected payload instead of defending or elaborating on the previous format.