refactor-tag-tree

When to use

The user's tag tree has accumulated drift: case variants (#AI, #ai, #Ai), spelling variants, near-synonyms, and singletons that should be folded into a hierarchy. This skill walks the user through consolidation one decision at a time.

Procedure

1. Call list_tags(min_count=1, include_hierarchy=True). Sort by with_descendants_count descending.
2. Detect issue classes from the returned list:
   • Case chaos: tags whose tag.lower() collides with another tag's tag.lower().
   • Singletons: tags with exact_count == 1 that aren't part of a hierarchy.
   • Near-duplicates: pairs where Levenshtein distance ≤ 2 (e.g. agents vs agent).
   • Orphan top-levels: top-level tags with no descendants where a hierarchy parent would be obvious (e.g. rag alone when research/ exists).
3. Surface ONE issue class at a time. Order: case chaos → near-duplicates → orphan top-levels → singletons. Don't dump the whole list.
4. For each issue class, propose specific renames. For case chaos, default to the lowercase form. For near-duplicates, the higher-count tag wins (with the user able to override).
5. Show usage counts and 2–3 sample paths per tag involved. The user MUST have enough context to make a judgment.
6. For each user-approved rename, call rename_tag(old=..., new=..., confirm=true) (or merge_tags if the target already exists and merge=True is needed).
7. After all renames in the issue class, call list_tags again. Re-check whether the issue is resolved before moving to the next class.

Output format (per issue class)

Found case chaos:
  #AI (12 uses, in [[notes...]])  ←
  #ai (37 uses, in [[notes...]])
  #Ai (2 uses, in [[notes...]])

Recommendation: merge into #ai (highest count, conventional lowercase).
Confirm? (yes / change target / skip)

Anti-patterns

• Don't do silent bulk renames. Every rename is a separate confirm.
• Don't propose hierarchy changes (#ai → #research/ai) without asking. That's the user's taxonomy.
• Don't touch tags that appear only in Dataview tags:: foo, bar inline fields. Those aren't real tags.
• Don't run on a vault where Obsidian is currently open — tag-tree refactor across hundreds of files while Obsidian holds buffers is asking for conflict. The user should close Obsidian (or open it read-only) before invoking this skill. (Automatic detection + refusal is on the v0.2 roadmap.)