# Obsidian Untangle Knot > 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. - Skill: `alexeyshishin/obsidian-untangle-knot` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add alexeyshishin/obsidian-untangle-knot` - Raw SKILL.md: https://api.skillmd.com/api/skills/alexeyshishin/obsidian-untangle-knot/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: alexeyshishin (https://skillmd.com/u/alexeyshishin) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/alexeyshishin/obsidian-untangle-knot --- # 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 (`/`):** 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: ```bash 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: ```bash # 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 ``` ```bash # 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:** ```bash # 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 . | wc -l # with pipe aliases ``` 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 ` – `: `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`: ```yaml --- 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: ```markdown ## Заметки - [[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: ```bash 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**: ```markdown ## Управление инфраструктурой → 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 ` – ` **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