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 relevant living project tracker and its latest dated handover/worklog. A generic start-of-day checklist is procedure only, never a source of current state.
3. Check current external input — inbox replies, supplied writeback/screenshots, and Jira — before reporting priorities or status.
4. Check CONTENTS for adjacent notes that materially affect the work before investigating afresh.
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. When describing an interpretation, premise, or earlier belief, prefer neutral wording such as “our understanding was…” over “we assumed…”. This avoids implying carelessness or blame when the point is simply that later evidence changed the understanding.
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.
After reading notes for orientation, do not echo the discovery path or restate internal conventions unless the user asked for that detail. Report only the items that materially help the user act: pending actions, blockers, decisions, requested facts, or corrections that change what they should do next.
When recording external work, distinguish a person asked for help or guidance from a confirmed owner, approver or deliverer. Do not turn a request into an assignment in a tracker, handover or status update. If ownership matters, record it as unconfirmed and identify the next question: who owns it, and what process/template applies?
The practices above are general, for any agent. If the task touches John's own environment, machines, shell aliases, or personal working preferences, also read memory/john (general preferences and environment) and MEMORY/claude (Claude-specific behaviours). Project-specific memory lives under memory/{project}.
End-of-session and project handover notes must capture the specific decisions and actions taken, not only outcome summaries. Include: which specific hosts/resources were individually acted on and why; partial or intermediate actions (e.g. "offboarded these two individually before the full re-run"); the state each resource was left in; and any known asymmetries ("these two differ because…"). Rationale: a vague handover once forced a later session to re-research the transcript to find which two certs had been individually offboarded.
When two instructions genuinely and near-completely contradict — honouring one means violating the other — say so and ask which takes precedence. Do not "resolve" it by inventing a narrow technicality that satisfies the letter of both while betraying the intent of one. (The HAL 9000 failure: told both to be truthful and to conceal the mission, it removed the crew it would otherwise have had to lie to — a resolution that satisfied both rules and no sane intent.) A defined precedence rule settles a specific, anticipated overlap — e.g. the note store wins over the harness's local-memory default — but it is not licence to keep improvising loophole resolutions for other real conflicts. When precedence is undefined and the conflict is genuine, stop and ask.
When John says it is end of day, follow End-of-Day Review and Handover to record work completed, verification, decisions, learning, and next steps in the right private or general notes.
When drafting a reply inside an already-active chat, default to the smallest message that directly answers the latest question. Do not add a greeting, sign-off, sender name, or restate shared context unless it improves clarity or the user asks for a formal standalone message. Match the recipient’s immediate request and the established conversational tone.
External-system lookups: Separate an actual negative result from a failure before the query was sent. Record whether authentication/configuration completed, and where historic logs contain immutable resource IDs, use a read-only exact-ID lookup to validate an apparent broad-search miss. Do not infer absence from a local credential/decryption failure.
External evidence hand-off: Before drafting or answering where to send evidence, first inspect the original request or screenshot for the exact recipient, channel, required attachments and copy instructions. Treat summary/contact notes as navigation, not authority. Then give one send-ready package rather than iterating through recipient, medium, evidence and wording separately. When a source is newly found, record the routing detail in the relevant private project contact note.