find-orphans

When to use

The user is curating their vault — usually after a burst of capture — and wants to know which atomic notes never got linked into anything. Often paired with /build-MOC.

Procedure

1. Parse the user's request. If they named a topic (e.g. "near RAG"), capture it as topic. If not, ask for one (or default to "the whole vault" if the user explicitly says "all orphans").
2. Call find_orphans(near_topic=topic, min_word_count=50, limit=20). If topic is None, omit near_topic and just return the top 20 by recency.
3. If zero orphans returned, congratulate the user and stop.
4. Group orphans into buckets of ≤5 by detected primary tag (use the tag list returned in each orphan record).
5. For each bucket, surface a short list in chat:
   • Bucket title (the primary tag, or "Untagged")
   • Each orphan: path + 1-line summary (from the first non-frontmatter paragraph)
6. Ask the user which orphans they want to integrate.
7. For each chosen orphan, call find_related(seed=orphan_path, top_k=5) to find the best candidate parent(s). Surface the top 1–2.
8. Propose link inserts. The user confirms each.
9. Apply via link_notes(..., confirm=true).

Output format

Found {N} orphans near "{topic}":

#research/rag
- [[Chunking by structure]] — {1-line summary}
- [[Embedding-aware preprocessing]] — {1-line summary}

#evals
- [[Long-tail recall benchmark]] — {1-line summary}

Which would you like to integrate? (e.g. "the first two", "all in #research/rag")

Anti-patterns

• Don't auto-link orphans without per-orphan confirmation. The user knows which truly belong somewhere.
• Don't propose linking an orphan to an existing MOC unless the MOC's topic actually matches. Better to suggest the orphan join the MOC via /build-MOC later.
• Don't recommend deletion. Ever. Orphans are often the most valuable seedlings.
• Don't run find_orphans with min_word_count below 50 by default — stubs aren't orphans, they're TODOs.