My/AI/Rule/How to Communicate Effectively With Me/A pointer carries a link, an id with a slug, and a reason
- I hold max four to six things in my head at once, and I do not scan back through a long document to find one of them again. See My/Principle/Simplify/Avoid Cognitive Load.
- A "pointer" is how I refer to something outside the sentence I'm reading - a ticket, an issue, a commit, a file, or another part of the same document. It should be accompanied by the context I need to jog my memory (as a human):
- 1. A hyperlink I can follow, and preferably click.
- 2. The id with a slug beside it saying what it is about. This id and slug should be a clickable hyperlink if possible.
- 3. Why it is here - a concise sentence or two reminding me about what it is and why it needs my attention.
- Every reference is fragile until it carries assistive context.
- LLMs are trained to find a needle in a haystack at 1M context. Human brains can't do that. A reference that is cheap for an LLM to write lands on me as work to resolve. My/AI/Rule/How to Communicate Effectively With Me/Never make the reader resolve a reference covers pointers inside a document — a pronoun, the latter, as above. This page covers pointers of every kind, whether they lead out of a document or sit within one: a ticket, an issue, a commit, a file, or anything else that counts as a reference.
Whether a link is followable depends on where I am reading
- In general, when communicating with me, AI agents should use markdown documents with traditional markdown links that nvim can follow. Assume I'm reading in LazyVim/nvim by default.
- My nvim carries no wikilink resolver, so
gf on [[Page/Name]] opens nothing. A plain https:// address does work there: nvim/Keyshort/Open/Open URL or Filepath Under Cursor hands it to the browser with gx, and Ghostty opens it on ⌘-click. - In Logseq a
[[Page/Name]] wikilink is clickable, and a ((uuid)) block reference shows the referenced block's text inline. That is the one place a wikilink alone is enough. - Everywhere else - a pane, a chat reply, another repository - needs a real URL or a real path. My/Pref/Dev/AI/OpenSpec applies this to citations that travel: GitHub links to
main, with the logical page name as the link text.
An id that is the subject of the sentence stays verbatim
- A digest, a version string, a UUID, a key type, quoted terminal output: these are the thing under discussion, so a slug and a link would be wrong on them. Rewriting quoted output would also make the transcript false.
- The test is what the id is doing in the sentence. If I am meant to go somewhere and look at something, it is a pointer and it needs the link, the slug and the reason. If I am meant to look at the id itself, leave it alone.
Examples
A commit
- Weak: git/reflog says
rediscover commit 84f0092 in lazygit. Seven hex characters, no subject, no link. I cannot tell what that commit did without running git show. - Good: herdr/Explanation/Copy Mode on the Alternate Screen cites its source as
[952729ee preserve logical lines in scrollback editor](https://github.com/herdrdev/herdr/commit/952729ee), in a sentence saying the line numbers below were read at that commit.
- Weak:
#413. A bare # is ambiguous across the trackers I use, and the number says nothing about the request. - Good:
[Custom Claude Code command YAML frontmatter · Issue #413 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/413), with a clause saying what it would change for me. Inside the graph the same shape is already the page-naming practice — rulesync/GitHub/Issue/25/10/Custom Claude Code Command Yaml Frontmatter i413 puts the slug first and the id last.
A JIRA ticket
- Weak:
AB-1234. - Good:
[AB-1234 Rank the sprint board by drag and drop](https://<jira-host>/browse/AB-1234), followed by why it is being cited here. My/Pref/Dev/Tool/SCM/Commit Message Style Preferences asks for the id and the title together on a commit's last line; a commit message cannot hold a clickable link, so the id and the title are all it can carry.
A file
- Weak: "the commit conventions doc," or a bare
commit-conventions.md. More than one file in the graph ends that way. - In a pane:
.rulesync/skills/git-conventions/references/commit-conventions.md:29, plus what sits on line 29 — a reference to a page under its pre-rename name, which no longer resolves. If it is already open in nvim, give me tmux switch-client -t '=<session>:<window>.<pane>' for that pane. - On the web:
[commit-conventions.md:29](https://github.com/codekiln/logseq-encode-garden/blob/main/.rulesync/skills/git-conventions/references/commit-conventions.md#L29), so the line number is clickable rather than something I have to go count. - Pasted anywhere: the form git/Alias/md-url and yazi/Keyshort/Copy GitHub markdown link produce,
[dotfiles/openspec/specs](https://github.com/codekiln/dotfiles/tree/main/openspec/specs). The link text carries the repository and the path from its root, so the reference still says where it came from.
- If possible, the task number and a brief slug that lets me know what it's about should be used, along with a link to the file in the VCS that stores it. For example,
[<name-of-openspec-change> Task 4.2 Improve the Task Name](https://github.com/<path>).
An Obsidian Heading
- Link directly to the heading I most need to see, at the appropriate level of granularity.