From 2904147d730d7e0d78a16159af8bc907f919c54f Mon Sep 17 00:00:00 2001
From: Roman Zhulpo <117448064+RomanZhulpo@users.noreply.github.com>
Date: Wed, 26 Aug 2026 20:57:50 +0200
Subject: [PATCH] instructions: split exists:false into drift, backlog and real
 breakage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A dangling wikilink is three different situations, and reporting them as one
list of 'broken' makes the report worthless — the real breakage drowns in it.

Measured on a 417-note memory vault with the same convention: of 311 wikilinks,
68 did not resolve. Only 13 were topics that had genuinely never been written,
and zero were true breakage. The other 55 were EXISTING notes written with a
different separator or without their type prefix — [[user-career-discretion]]
for user_career_discretion.md. That drift is structural rather than careless:
filenames carry a type prefix nobody repeats when linking by meaning, so it
regenerates continuously and is not worth a human's attention. It is repaired
mechanically.

The backlog class matters most. In an agent memory layer a dangling [[name]] is
often deliberate — it marks a note worth writing later. Flagging those as errors
teaches the reader to ignore the whole report, which is how a link audit stops
working.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 instructions.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/instructions.md b/instructions.md
index 3cad13f..1ab4488 100644
--- a/instructions.md
+++ b/instructions.md
@@ -24,7 +24,15 @@ ram-brain — общий git-бэкапленный «второй мозг» д
   (например `[[projects/ram/overview]]`). Голый `[[basename]]` резолвится, только если
   файл `basename.md` лежит в корне vault — иначе ссылка битая. НЕ ссылайся на слаги из
   локальной памяти агента (`~/.claude/.../memory/`) — в vault их нет. После правок проверяй
-  здоровье ссылок через get_outlinks / get_broken_links (`exists:false` = битая).
+  здоровье ссылок через get_outlinks / get_broken_links.
+- `exists:false` — это три разных случая, и лечатся они по-разному. Не своди их в один
+  список «битых», иначе отчёт становится шумом и настоящие поломки в нём тонут:
+  - **дрейф именования** — та же заметка, записанная иначе (`[[user-career-discretion]]`
+    при живом `user_career_discretion`). Чинится механически, человеку показывать нечего;
+  - **backlog** — ссылка на тему, которую ты сознательно ещё не написал. Это не дефект,
+    а пометка «здесь стоит завести заметку». Показывай отдельным списком;
+  - **поломка** — переименовали или удалили цель, либо совпадений несколько и надо
+    выбрать. Только это заслуживает красного статуса.
   Учти: в веб-интерфейсе GitHub синтаксис `[[...]]` не кликается — это движок mcp-md/Obsidian,
   а не сам git.