dekko-notes

Keeping dekko notes current

dekko stores symbol-anchored notes in .dekko/notes.json, keyed by symbol id (path::Qualified.name). They are committed to git and shown inline by query_symbol / get_context_pack (CLI: dekko query symbol / dekko context). See the dekko-orient skill for target syntax (bare name, Class.method, file.py:name, or the tolerated :: form) and for when to reach for dekko over grep/Read generally.

Consult notes before editing

Whenever you pull a symbol's context, read any note: lines first — they record rationale, gotchas, and constraints the code alone does not show. Treat a note as settled context: don't re-derive what it already tells you by reading the code again. Call the list_notes MCP tool (or dekko note list <sym>) directly if you need to see a symbol's notes outside a context pack, or dekko note list with no target to see every note in the repo before a large change.

If a note turns out to be wrong or obsolete, fix it (note rm then note add) rather than leaving it to mislead the next reader.

Write a note after a non-obvious change

After a change whose reasoning is not evident from the diff — a workaround, an invariant that must hold, a deliberate trade-off — add a note so the next reader (human or agent) sees it. Call the add_note MCP tool directly, or:

dekko note add path/to/file.py:func "why this is the way it is"

Keep notes short and about why, not what.

Re-anchor notes when a symbol moves

Note ids embed the file path and qualified name, so renaming or moving a symbol orphans its notes. After such a change:

1. Find orphans: dekko note list --orphaned.
2. For each orphan that still applies, re-anchor it to the new id:

   dekko note add <new-target> "<the note text>"
   dekko note rm  <old-target>
   

   (the old id is shown in the orphaned listing).
3. Remove notes that no longer apply: dekko note rm <old-target>.

Run this sweep after any rename, file move, or signature change that alters a symbol's qualified name.