obsidian-untangle-knot

name

obsidian-untangle-knot

description

Offload an Obsidian hub note that too many notes link to (an in-degree tangle). The main signal of a tangle is a high in-degree (tens to hundreds of incoming links); out-degree is secondary. The skill creates sub-MOCs under the hub's existing categories and **redirects incoming links from resource notes** to the specific sub-MOC instead of the general one. The original MOC is kept as an entry point — it can still be linked to when the category is unclear. Use this skill whenever the user says: "untangle this knot", "offload MOC X", "too many links to X", "re-link these notes", "X has grown too big", "this map has become useless", "I don't see structure in this MOC", "too many incoming/outgoing links", "process this hub note", "find my hub notes", "link dump", "junk-drawer map". Also apply it when it's clear from context that the user means an overloaded graph node, even if they didn't call it a hub.

obsidian-untangle-knot

Core idea

In a personal knowledge base, dozens or hundreds of notes end up linking to the same MOCs — that's natural: when you add an article, a book, or a new idea, it's easier to link to the general [[DevOps]] than to hunt for the specific sub-map. Over time the general MOC turns from a map into a backlink dump: you open it and drown in noise.

Out-links on a hub grow slowly (it's still a map, deliberately maintained). In-links grow spontaneously and fast. So the main signal of a tangle is high in-degree, not out-degree.

The skill:

1. Finds/accepts a hub and counts its in/out links
2. Relies on the hub's already-existing structure (subheadings, explicit categories) as ready-made landing points — it doesn't invent new categories when none were asked for
3. Creates a sub-MOC for each category
4. Main action: goes through incoming links from resource notes and switches them from the general MOC to the appropriate sub-MOC
5. The original MOC stays — it remains the right entry point for the "don't know exactly where to link" case

before:                       after:
                             [hub] (~ stays, but fewer in-links)
[hub] ←── 200 in-links       ├── [sub-MOC A] ←── 60 in-links (former general ones)
  ├── 22 out-links           ├── [sub-MOC B] ←── 40
                             ├── [sub-MOC C] ←── 30
                             └── [sub-MOC D] ←── 25
                             (general, unclassified ~45 — stay on the hub)

Base rules (PARA, tags, templates, style, naming) — in .claude/rules/. In particular: knowledge-structures.md (MOC), note-types-frontmatter.md (frontmatter), workflows.md (plan → confirmation → action protocol), file-naming.md (names).

Vault root folder (<vault>/): set at install time (--vault or the OBSIDIAN_VAULT env var). See .claude/rules/vault-struct.md. Output language: Russian, technical terms in English.

---

When to use this and when not to

Situation	Skill
A single note/MOC overloaded with links	this skill
The content of a single note needs splitting into atomic notes	obsidian-split-note
Lecture notes — extract concepts	obsidian-refactor-lecture
Cross-check a single note for contradictions and gaps	obsidian-note-critic
Inbox notes — sort and file them	obsidian-refactor-inbox
Update a single note's frontmatter	obsidian-enrich-note
Visual callout map of a single note	obsidian-note-canvas-map

Difference from obsidian-split-note: that skill splits the content of a single note into atoms. Here we split links (the graph), not text — the note body is rewritten into a table of contents, and no new atomic notes are created.

---

Algorithm

1. Choosing the hub note

Two modes.

Direct — the user already named the note ("offload [[DevOps]]"). Find the file by name:

fd -t f "DevOps.md" .

If there are several matches, ask which one.

Discovery — the user wants to find candidates ("find my hub notes", "where am I overloaded"). Scan 02. Сферы/07. Карты/ (by default) or another folder on request:

# Count out-links: number of [[wikilink]] in the body + frontmatter
for f in "02. Сферы/07. Карты/"*.md; do
  out=$(rg -o '\[\[[^\]]+\]\]' "$f" | wc -l)
  echo "$out  $f"
done | sort -rn | head -10

# Count in-links: how many times the note is linked to
rg -c -F "[[Note name]]" .

Show the top-10 by in + out and ask which one to offload. Thresholds — see step 2 below.

2. Counting links and diagnosis

In-links are three distinct streams, not one metric. This matters a lot: a link from a neighbor's up: and a link in an article's body are different phenomena with different handling strategies. Ignoring the distinction means doing the job incompletely.

Stream	What it is	How to find it	Re-linking
A. Hub's out-neighbors	Notes that the hub links to (from the body or down)	Parse the hub's body/frontmatter	Iteration 1 (scaffold)
B. Up-children	Notes with up: [[Hub]] in their frontmatter that are not mentioned in the hub's body	Scan the frontmatter of all notes	Iteration 1 (scaffold) — don't skip this!
C. In-links in bodies	Contextual mentions of [[Hub]] in the body of other notes	rg -F "[[Hub]]" across bodies	Iteration 2 (heavy, optional)

Counting:

# Stream A: out-degree
# In the hub's body — wikilinks via regex \[\[([^\]\|#]+)
# In the hub's frontmatter — up, down, other, links, sources

# Stream B: up-children — ONLY from the `up:` field, not from other frontmatter fields!
# A crude frontmatter grep also catches unrelated hits: [[Hub]] can appear in other/links/category/sources —
# that's different semantics, and re-linking those is NOT allowed.
# Parse precisely — only the multi-line or single-line up: form
python3 - <<'PY'
import os, re
res = []
for dp, _, fns in os.walk('.'):
    for fn in fns:
        if not fn.endswith('.md'): continue
        p = os.path.join(dp, fn)
        try:
            with open(p, encoding='utf-8') as f: c = f.read(4000)
        except: continue
        m = re.match(r'^---\n(.*?)\n---', c, re.DOTALL)
        if not m: continue
        fm = m.group(1)
        # Multi-line (up:\n  - "[[X]]"\n  - ...)
        block = re.search(r'^up:\s*\n(.*?)(?=^[a-zA-Z_]+:|\Z)', fm, re.M|re.S)
        if block and re.search(r'-\s*"?\[\[Hub\]\]"?', block.group(1)):
            res.append(p); continue
        # Single-line (up: "[[X]]")
        s = re.search(r'^up:\s*(.+)$', fm, re.M)
        if s and '[[Hub]]' in s.group(1):
            res.append(p)
print(len(res))
PY

# Stream C: in-links in bodies (overall count)
rg -l -F "[[Hub]]" --type md . | wc -l
rg -l -F "[[Hub]|" --type md . |  -l  

Record:

• A = unique out-degree
• B = unique up-children
• C = unique in-links in bodies
• The overlap A ∩ B (an out-neighbor that also has up: [[Hub]]) is handled under stream A (it covers both cases)

Why this matters: Stream B is the most "forgotten" load. A note has up: [[Hub]] but isn't mentioned in the hub's body. If you only offload stream A, these notes are left with a stale categorization.

Important note on other frontmatter fields:

[[Hub]] can show up in several frontmatter fields — each with its own semantics:

Field	What it is	Touch it during offload?
up	Parent in the PARA/MOC hierarchy	Yes — this is stream B
other	Horizontal link, a related topic	No — it's a contextual link, not a category
links	External links or related wikilinks	No — navigation, not categorization
category	User-defined catalog field (books/articles/videos — a "shelf")	No — this is categorization by content type, not by topic
sources	Sources (literature wikilinks or plain text)	No, never — a record of sources
down	Child notes (on the hub)	Part of stream A

If you mix these up and touch [[Hub]] in other/links/category, you'll break the semantics. The skill must parse the YAML precisely and only work with the up field.

"Tangle" threshold (by in-degree):

in-degree	Diagnosis	Action
≥ 100	Strong in-tangle	Untangle it (this skill)
50–100	Emerging in-tangle	Can be untangled; ask the user
20–50	Weak tangle	Untangling is possible, but the gain from re-linking is small
< 20	Not a tangle	Probably too early

Out-degree affects whether untangling is feasible at all:

• N < 5 with high in → nowhere to untangle into, there's not enough to build sub-MOCs from. The skill declines and suggests obsidian-ingest or obsidian-note-critic.
• N = 5–10 → 2–3 categories can be put together, if they're already outlined by subheadings
• N > 10 → there's room for proper categorization

High out with low in (out=30, in=5) is an out-tangle, which is rare in your base (out grows more slowly). The scenario is different: the hub's body gets rewritten into a table of contents, and sub-MOCs are created for the sake of tidiness. This is the "light branch" of the skill, see the special case below.

3. Reading the neighbors (no changes)

For each of the hub's out-neighbors — a quick read and classification:

• Does the file exist? If the wikilink is dangling, it's not a neighbor but an empty link. Record it in a separate "dangling out-links" list; it does not go into the up re-linking.
• File name and path
• Thesis (one phrase — taken from the first meaningful line of the body or from aliases)
• Structural tag and PARA folder
• confidence (if present)
• up — the most important field. Its value determines the re-linking branch in step 6.2:
  • up is empty → add the sub-MOC
  • up contains [[Hub]] → replace it with the sub-MOC
  • up contains [[Some – Alternative – sub-MOC]] that exists as a file → leave it alone, the note already has a categorization (see below)
  • up contains a wikilink that doesn't exist (dangling) → pick up the intent: it's an attempted categorization, route it to the new sub-MOC

Classifying the neighbor:

Neighbor type	Action
Atomic note / concept (#thought)	standard re-linking
MOC / map (#moc, MapOfContent)	standard re-linking; add as down on the new sub-MOC
Mention note (#person, a link to a company, a tool)	not considered a categorizable neighbor — stays on the hub as a contextual link, doesn't move to the sub-MOC
Note from 02. Сферы/04. Личный блог/ (blog/content)	has its own lifecycle (status); don't touch up
Note whose up points to an existing alternative sub-MOC	already categorized — leave it; add the alternative to the new sub-MOC's other as a related map

Don't read the full body — the thesis and frontmatter are enough for categorization. If the thesis is unclear, look at the first heading.

4. Categorization

The main principle: sub-MOCs are landing points for future in-links. A category needs to be "semantically stable" enough that it can meaningfully be linked to from a new note.

If the hub is already structured with subheadings (## sections), use them as ready-made categories. Don't invent axes if the map's author has already done that work. It's enough to turn subsections into sub-MOCs, even if they have just 3–4 notes each. This is gentler and preserves the author's mental model.

If there are no subheadings, pick the axis from the table below that best fits the material:

Axis	When to apply	Example categories
By knowledge domain	When the hub mixes several fields	SRE, Economics, Psychology
By level of abstraction	When the hub is a large discipline	Principles, Tools, Experience, Sources
By artifact type	When neighbors differ in nature	Concepts, Literature notes, Syntheses, Projects
By maturity level	When confidence is present	Confirmed, Disputed, In progress
By existing tags	When frontmatter already has a stable taxonomy	per tags.md

Category size:

• Minimum 2 notes if the category is already outlined by a subheading or existing structure — it's "semantically stable", so a sub-MOC is justified.
• Minimum 3 notes if the category is invented from scratch — otherwise it's just noise.
• If a category has > 20, it's a tangle in its own right — split it internally (a 2-level structure: Hub → group → sub-MOC).

Category name — claim-based, per file-naming.md. For a family of sub-MOCs from the same parent, use the format <Parent> – <Category>: DevOps – Управление инфраструктурой, DevOps – Деплой и релиз. This preserves kinship in the graph.

A "Misc" section in the hub is where the singletons go — the ones that don't fit any category. Don't build a sub-MOC for them.

Stop signal: if no axis produces categories, the material is monolithic. There's nothing to untangle. Say so and suggest obsidian-note-critic.

5. Offload plan → confirmation

The offload happens in two iterations — scaffold and in-links. This matters: the actual drop in in-degree only comes in the second one. Don't promise the user miracles after the first.

Iteration 1 (scaffold, safe):

• Create the sub-MOCs
• Re-link up on the out-neighbors (stream A)
• Re-link up on the up-children (stream B) — can be many times larger than A
• Minimally update the hub's body (pointers, frontmatter down)

Both up re-linkings are combined — these are frontmatter edits, a symmetric and safe operation. Split into sub-batches only if up-children > 50: batches of 10–20 at a time, by category/folder.

Iteration 2 (in-links in bodies, optional):

• Redirect in-links in bodies of resource notes (stream C)
• This is heavier: it needs the context of the link to determine the category
• Really applicable only to notes where [[Hub]] is the central topic of discussion. For most mentions of [[Hub]], it's a related contextual link, and re-linking it breaks the meaning of the text
• This iteration may turn out to be barely needed — if in-degree has already dropped by the expected amount after iteration 1

Plan format:

🧶 Hub: [[DevOps]]
   in: 222   out: 22   type: MOC
   dangling out-links: 4 (Deployment Pipeline, Change Management, GitOps, ChatOps)
   neighbors with an alternative up: 2 (Blue-Green, Canary — linked to [[Стратегии развертывания...]])

═══ Iteration 1 (scaffold) ═══

Create sub-MOCs (in 02. Сферы/07. Карты/):
  1. [[DevOps – Основы]]                       → 3 out-links
  2. [[DevOps – Управление инфраструктурой]]   → 4
  3. [[DevOps – Деплой и релиз]]               → 1 (Blue-Green/Canary stay on the alt. map)
  4. [[DevOps – Процессы и подходы]]           → 1 (GitOps/ChatOps dangling)

Misc (singletons, stay on the hub): DORA Metrics, Culture, Security, DevSecOps

Re-link `up` on out-neighbors: ~8 notes (after filtering out dangling/alternative/mentions)

Minimally update the [[DevOps]] body:
   — a pointer line `→ Sub-map: [[sub-MOC]]` in each corresponding ## subheading
   — frontmatter `down`: add links to the new sub-MOCs
   — Don't rewrite the whole body: the structure is already there

Expected effect: the original's in-degree will drop only slightly (~5–10),
                  because the links in the bodies remain. The scaffold is in place.

═══ Iteration 2 (in-links, separate run) ═══

Redirect in-links in the bodies of resource notes:
   Total resource in-links: ~160
       — 03. Ресурсы/<Тема>/База знаний/        131  ← heavy, split into sub-batches
       — 02. Сферы/07. Карты/           17
       — 03. Ресурсы/<Тема>/           5
       — 03. Ресурсы/Книги/            3
       — 03. Ресурсы/<Тема>/<Источник>/    3
       — 03. Ресурсы/<Тема>/            1
   Not touching (~60): 01. Проекты/, 02. Сферы/, 05. Дневник/, 04. Архив/, 00. Входящие/

Expected effect: the original's in-degree will drop by 50–70% (from the resource mass).

Wait for confirmation on each iteration separately. After iteration 1, show the report and ask whether to proceed to iteration 2.

Confirmation exceptions — same as in workflows.md: "just do it", "no confirmation needed".

6. Execution

The order of steps matters, so you don't end up with broken links at intermediate stages:

6.1. Create the sub-MOCs

In 02. Сферы/07. Карты/, from 08. шаблон карты.md:

---
aliases: []
tags:
  - moc
up:
  - "[[Original hub]]"
down: []   # will be filled with links to the category's notes
links: []
other: []
---

In the body — a short description of the category (1–2 sentences) and a list of links:

## Заметки

- [[Note 1]] — what's in it
- [[Note 2]] — what's in it

## Связанные карты

- [[Neighbor MOC]]
- [[Alternative sub-MOC]] — a related map, if a parallel categorization already exists for the topic

If, in step 3, some neighbor was found to already have an existing alternative sub-MOC (e.g., Blue-Green is already linked to Стратегии развертывания приложений в Kubernetes), add that sub-MOC right away to the other field of our sub-MOC and to the "Связанные карты" section. This respects the author's prior categorization — we don't duplicate it, we reference it.

6.2. Re-link up on out-neighbors

For each out-neighbor, determine the branch based on step 3's result and act accordingly:

Branch A — up points to the hub itself ([[DevOps]]):

Replace it with [[sub-MOC]]. If up has several parents, replace only the link to the hub, leave the rest.

Branch B — up is empty:

Add [[sub-MOC]] (not the hub) — we set the correct categorization right away.

Branch C — up contains a dangling wikilink (e.g., [[DevOps – Практики]] which doesn't exist as a file):

This is the author's intent to categorize — pick it up. Replace the dangling link with the actual sub-MOC ([[DevOps – Процессы и подходы]] in our example). This matters: the author already tried to create a category, and we're closing that loop.

Branch D — up contains an existing alternative sub-MOC (e.g., [[Стратегии развертывания приложений в Kubernetes]], the file exists):

Don't touch it. The note is already categorized, it has its "own parent". In the offload plan, this note is listed as "stays on the alt. map", and in our new sub-MOC we reference the related map via other and "Связанные карты".

Branch E — mention neighbors (#person, a link to a company, a tool):

Not considered categorizable. Don't touch up, the note stays on the hub as a contextual link.

Branch F — blog/content notes (02. Сферы/04. Личный блог/):

Don't touch up — these notes have their own lifecycle (status).

Branch G — the neighbor's up already has a more precise parent, and [[Hub]] is redundant:

When up: [[Other MOC]], [[Hub]], and the other MOC is semantically more precise for this note (e.g., Incident Management has up: [[Site Reliability Engineering]], [[DevOps]] — it's about SRE/ITSM, not a DevOps subcategory), the right action is to remove the link to the hub from up, not re-link it.

Sign of branch G: none of our sub-MOCs fit semantically, and the note already has another parent that's more precise. This is a sign that [[Hub]] in up was an erroneous double-link — navigational, not categorical.

Don't confuse this with branch D: in D, the note is already categorized by an alternative sub-MOC (of the same family as the hub) — there, the alt. parent is a different categorization of the same topic. In G, the note is about a different topic, and the hub was simply redundant.

Bonus fix along the way: if a note's body has dangling wikilinks left over from an old attempt to categorize the hub (e.g., [[DevOps – Практики]] — a nonexistent file), it's worth replacing them with an actual wikilink ([[DevOps|практиками DevOps]] via a pipe alias, or a matching sub-MOC). This is incidental graph hygiene, not the skill's main job.

General nuances:

• Preserve the list/string format (YAML) as it is in the source note.

6.3. Redirect in-links (the main step)

This is the skill's primary action. Get the list of all notes that link to the original:

rg -l -F "[[Hub name]]" --type md . > /tmp/in-links.txt

Folder filter (important):

Only notes of an informational/resource nature are eligible for re-linking:

• ✅ 03. Ресурсы/<Тема>/ (any subject folder, including Книги)
• ✅ 03. Ресурсы/<Тема>/<Источник>/ (a source's own takeaway folder)
• ✅ 03. Ресурсы/<Тема>/База знаний/ (concepts, thoughts)
• ✅ 02. Сферы/07. Карты/ (other MOCs)

Don't touch — links made intentionally as a "general entry point"; re-linking them breaks the historical context:

• ❌ 01. Проекты/ — project notes deliberately link to the general MOC
• ❌ 02. Сферы/02. Работа/ — meetings, 1:1s — contextual links
• ❌ 05. Дневник/ — journal, historical context
• ❌ 04. Архив/ — archived material
• ❌ 00. Входящие/ — unprocessed, leave for obsidian-refactor-inbox

For each eligible note:

1. Read the context around the link (one or two lines around it)
2. Determine which category the note's material belongs to
3. If it's determinable — replace [[Original]] with [[Sub-MOC]] in the note's body
4. If it's not determinable, or it's a general context — leave [[Original]] as-is. This is the correct behavior: the general MOC is indeed a "general entry point".
5. If a single note has several links to the original, handle each one separately — they might go to different sub-MOCs.

Don't touch links inside:

• > [!quote] and > [!note] callout blocks — these are historical quotes
• sources in frontmatter — a record of sources
• Callout blocks explicitly marked "Review", "Change history", "Context"

Borderline cases (category unclear, the note sits on the fence) — leave the original link and list them in the "Under question" section of the report.

6.4. Minimally update the original hub's body

Don't rewrite the hub's body from scratch. Structuring by subheadings is the author's mental model, and it's valuable. It's enough to insert links to the sub-MOCs.

If the hub has subheadings (## Category):

For each subheading we extracted into a sub-MOC, add a compact pointer as the first line after the heading:

## Управление инфраструктурой

→ Sub-map: [[DevOps – Управление инфраструктурой]]

- [[Infrastructure as Code (IaC)]]
- [[Infrastructure from Code (IfC)]]
    - [[Сравнение и отличия между IaC и IfC]]
- [[Configuration Management]]

Don't touch the existing out-links under the heading — they stay as convenient navigation. The sub-MOC and the hub show the same information at different levels of detail.

If the hub has no subheadings and the body is a flat list:

Group the links by category, add subheadings. This is already a more substantial restructuring of the body, but preserve the order and wording where possible.

In the original's frontmatter:

• Add wikilinks to the new sub-MOCs in down (alongside the existing down entries)
• Leave everything else (up, aliases, links, other, tags, Bases/Dataview) untouched

6.5. Fill in down on the sub-MOCs

In each sub-MOC's down, list all the notes that now have up: [[Sub-MOC]]. This can be done manually (as in the plan) — no need to rescan.

7. Report

After iteration 1 (scaffold) — a mandatory caveat:

✅ The offload scaffold for [[DevOps]] is in place

   in (exact [[DevOps]]):  192 → 191  (−1)
   in (via pipe):            30 →  30   (=)

⚠️ Note: the original's in-degree dropped only slightly — that's expected.
   We only re-linked `up` in frontmatter (8 neighbors).
   Links to [[DevOps]] in the bodies of resource notes remain.
   The real effect will come after iteration 2.

Sub-MOCs created: 4
  [[DevOps – Основы]]                       in=3
  [[DevOps – Управление инфраструктурой]]   in=8
  [[DevOps – Деплой и релиз]]               in=5
  [[DevOps – Процессы и подходы]]           in=5

`up` re-linked on out-neighbors: 8 (out of 22 after filtering)

Under question / separate work:
  • Dangling out-links on the hub: [[Deployment Pipeline]], [[Change Management]],
    [[GitOps]], [[ChatOps]] — no notes exist, placeholders remain on the hub.
  • Alternative categorization: [[Blue-Green]], [[Canary Deploy]]
    stayed on [[Стратегии развертывания приложений в Kubernetes]];
    this map was added to the new "Деплой и релиз" sub-MOC's `other`.

Proceed to iteration 2 (redirecting ~160 in-links in bodies)?

After iteration 2 (in-links):

✅ [[DevOps]] offloaded

   in:  191 → 60–80   (real drop)

In-links redirected by sub-batch:
   03. Ресурсы/<Тема>/База знаний/    105 of 131
   02. Сферы/07. Карты/       13 of 17
   03. Ресурсы/<Тема>/       3 of 5
   03. Ресурсы/Книги/        2 of 3
   03. Ресурсы/<Тема>/<Источник>/  2 of 3
   03. Ресурсы/<Тема>/        1 of 1

Kept as-is: ~60 (outside the resource area — intentional general links) +
                  ~10 resource notes where the category was unclear (see "Under question")

Under question (10):
  • [[Note X]] — between "Deployment" and "Processes"; left as [[DevOps]].
  ...

If anything new turned up along the way (a neighboring note is also a hub, a contradiction between two neighbors, duplicates within a category), mention it in the report, but don't go there in the same iteration.

---

Special cases

A note isn't a MOC but has accumulated links

An atomic note/concept has spontaneously become a hub (e.g. Kubernetes with 30 links). Two options:

1. Turn it into a MOC — if the note is essentially already a map. Change #thought → #moc, update the frontmatter per 08. шаблон карты.md, move it to 02. Сферы/07. Карты/. Backlinks won't break — Obsidian updates them on rename.
2. Keep it as a concept — if the content stands on its own and deserves to remain a concept. Offload the links (categorize neighbors into sub-MOCs), but don't rework the note itself.

Ask the user at the moment the hub is chosen.

No category emerges

If no axis yields ≥3 notes per category, the material isn't a tangle. Say so directly:

There are a lot of links, but there's no categorical structure among them — the neighbors are all in one semantic field. This isn't a tangle, it's genuinely the center of the topic. There's nothing to untangle.

Suggest obsidian-note-critic for a deeper look, or obsidian-split-note if the note is large.

In-links to the hub from project notes

Don't re-link references from 01. Проекты/, 02. Сферы/, 05. Дневник/, 04. Архив/, 00. Входящие/. These links were made as a "general entry point"; re-linking them breaks the historical context. Only re-link in-links from resource notes (03. Ресурсы/).

The hub is already partly structured

If the hub has subsections in its body (## Принципы, ## Инструменты), that's the author's ready-made categorization — use it, don't invent one from scratch. It's enough to move each subheading out into its own sub-MOC and add a compact pointer at the start of the section.

Out-tangle (low in, high out)

Rare in this base (out usually grows more slowly), but possible — e.g., a freshly assembled large map that was just put together. Scenario:

• Re-linking in-links isn't needed (there are few of them)
• The main action is rewriting the hub's body into a table of contents by sub-MOC
• Sub-MOCs are created for the sake of graph tidiness, not to redirect a flow of links

If you land on an out-tangle, ask the user what effect they want (navigation vs. graph-view load). The action is chosen based on that answer.

Concept-hub (an atomic note with a large in-count)

An atomic note/concept (like Kubernetes) has accumulated in-links. Two options:

1. Turn it into a MOC — if the content already reads more like a map. Change #thought → #moc, move it to 02. Сферы/07. Карты/. Obsidian will update backlinks on rename.
2. Keep it as a concept + create a MOC alongside it — if the content stands on its own and is valuable as a concept. Create Kubernetes – MOC.md, and redirect the in-links there; the concept stays a narrow "definition/idea" object.

Ask the user at the moment the hub is chosen.

Bidirectional links (a note in both up and down of the original)

A symptom of confusion. Show them explicitly: "in both up and down at once: N notes". Ask which direction to keep. By default: the more general one stays in up, the more specific one in down. There should be no bidirectional link.

---

What NOT to do

• Don't delete the original — it stays as the root MOC, the top level of the table of contents and the general entry point.
• Don't rewrite the hub's body from scratch if it's already structured with subheadings — add a pointer to the sub-MOC, don't break the author's mental model.
• Don't re-link references outside 03. Ресурсы/ — projects, journal, conferences, archive, inbox are left untouched; their links to the general MOC are intentional.
• Don't ignore a neighbor's existing up. If it points to a dangling link, pick up the author's intent. If it points to an existing alternative sub-MOC, respect it and leave it alone — add that map to the new sub-MOC's other as a related map.
• Don't treat mentions of people and companies (#person, [[Some Company]]) as categorizable neighbors — they stay on the hub as contextual links.
• Don't touch blog/content notes in 02. Сферы/04. Личный блог/ — they have their own lifecycle (status).
• Don't try to re-link a dangling out-link on the hub — there's no note, the placeholder stays on the hub until it's manually created via obsidian-ingest.
• Don't touch links inside > [!quote], > [!note], > [!warning], and other callout blocks — that's historical context or quotes.
• Don't move neighboring notes between PARA folders — we're re-linking connections, not migrating structure.
• Don't do recursive offloading — one hub per run.
• Don't merge the scaffold and in-links into one iteration — after the scaffold, let the user see the result and decide whether to go into the heavy part.
• Don't clear links and other on neighbors — only up is subject to replacement.
• Don't invent categories when the hub already has ready-made subheadings — use what's there.
• Don't promise a big drop in in-degree after iteration 1 — that's the scaffold; the real effect comes in the second iteration.

---

Checklist before finishing

Sub-MOCs:

• Created in 02. Сферы/07. Карты/ with #moc and frontmatter per 08. шаблон карты.md
• up points to the original hub
• down is filled in (manually as a list, or via Dataview)
• Names contain no forbidden characters (file-naming.md); format <Parent> – <Category>

Out-neighbors (notes the hub links to):

• up re-linked from the original to the matching sub-MOC (where applicable per the structural tag)

In-links (the main part):

• Went through the eligible in-links only (the folders listed in 6.3 — 03. Ресурсы/ subject folders and 02. Сферы/07. Карты/)
• Where the category was clear — replaced [[hub]] with [[sub-MOC]]
• Where the category was unclear — left as-is, listed under "Under question"
• Didn't touch 01. Проекты/, 02. Сферы/ outside 07. Карты/, 05. Дневник/, 04. Архив/, 00. Входящие/
• Didn't touch callout blocks or sources

Original hub:

• Body — minimally updated (a pointer at the start of each subheading), not rewritten wholesale
• down extended with the new sub-MOCs
• Bases/Dataview, aliases, up, links, other, tags — unchanged