Knowledge Wiki Cluster

Knowledge Wiki Cluster

Detect clusters of concepts that share an implied parent slug, then decide for each child whether to fold (merge content into parent and delete the child) or link (keep the child as a standalone concept linked to the parent). The goal is to reduce total concept count by absorbing thin, redundant, or retired sub-concepts into a parent article.

Two cluster types are handled:

• New-parent (parentExists: false): the implied parent concept does not exist yet — create it, then fold/link/merge children.
• Existing-parent (parentExists: true): the implied parent already exists and these children have not yet been dismissed — fold/link/merge each one.

For new-parent clusters, each concept is grouped under its non-existing prefix ancestors up to (but not including) its nearest existing ancestor — so apple-watch-ultra forms an [apple-watch] cluster when apple-watch.md is absent, even if apple.md exists. For existing-parent clusters, the concept is grouped directly at its nearest existing ancestor. Presents one cluster at a time with a batch recommendation — you confirm, override, or dismiss.

Within a cluster, children may also be merged into each other (sibling merging) before any folding into the parent. A child judged not worth folding into the parent — an Anchor — can absorb another child's content if that child — a Fold-candidate — is a strict subset of the Anchor's content. The absorbed Fold-candidate is merged into the Anchor and deleted; the Anchor is recommended to stay standalone and is not expected to be folded into the parent.

Steps

1. Establish the working directory

The knowledge base root is the Git repository root. Run git rev-parse --show-toplevel and store the result as KNOWLEDGE_PATH.

2. Find clusters

Run:

node {KNOWLEDGE_PATH}/scripts/wiki/candidates.mjs find-implied-parent-concepts

This outputs { "clusters": [...] } sorted deepest first (most hyphens in impliedParent), with ties broken by cluster size descending. Both new-parent and existing-parent clusters are interleaved in this single ordering. Each entry has:

• impliedParent — the parent slug
• children — array of { path, dismissed } objects, where path is the concept file path (e.g. Wiki/Concepts/audi-etron.md) and dismissed is true if this child was previously dismissed from this cluster pair, false otherwise
• parentExists — false if the parent concept needs to be created; true if it already exists

A cluster appears only when it has at least the usual number of dismissed: false children (≥2 for new-parent, ≥1 for existing-parent). Previously dismissed children are included with dismissed: true as potential Anchor targets for sibling merges.

Derive each child's slug from its path field: Wiki/Concepts/audi-etron.md → audi-etron. Use this slug wherever {child-slug} appears below.

If the clusters array is empty, print No clusters found. and stop.

3. LLM pre-filter

For new-parent clusters only (parentExists: false), auto-dismiss clusters where the implied parent is a common English modifier rather than a meaningful proper noun or specific topic — e.g. smart grouping smart-home with smart-money, or the grouping the-economist with the-expanse. Children spanning clearly unrelated domains are a reliable signal for auto-dismissal. Skip this filter for existing-parent clusters — the parent's existence already confirms it is a real topic.

For each auto-dismissed cluster, run once per child:

node {KNOWLEDGE_PATH}/scripts/wiki/wiki-state.mjs dismiss-pair knowledge-wiki-cluster "Wiki/Concepts/{impliedParent}.md" "Wiki/Concepts/{child-slug}.md"

Be conservative — wrongly dismissed pairs require manually editing Wiki/.state.json to recover.

4. Present and resolve each cluster

Process one cluster at a time. Use a separate interaction for each cluster — never combine multiple clusters into a single question, even if you intend to recommend the same action for several in a row. When using AskUserQuestion, pass exactly one question per call. Never use the multi-question form to batch clusters.

Maintain an in-memory processed set of impliedParent slugs handled in this session. After creating a parent, exclude already-processed slugs from the refreshed cluster list.

4a. Read, summarize, and assess

Determine the Display Name for the implied parent before presenting:

• If parentExists is true, read the parent concept file and take the Display Name from its H1 heading (# …). This preserves the exact capitalisation already in use (e.g. ios → "iOS", macos → "macOS").
• If parentExists is false, derive a human-readable name from the slug (e.g. audi → Audi, apple-watch → Apple Watch, career → Career).

Read every child concept file, then classify each one in two passes:

1. Fold vs. Anchor. dismissed: true children are Anchors automatically — the previous decision that they don't belong as primary children of this parent stands; no independent judgment needed. For dismissed: false children, independently judge each as a Fold-candidate (thin, narrow, or low-standalone-value — would fold into the parent) or an Anchor (substantive: rich prose, multiple sources, or broad cross-links — would stay standalone). This judgment must not depend on any other child in the cluster.
2. Sibling merges. For each dismissed: false Fold-candidate, check whether its content is a strict subset of any Anchor's content in the same cluster (whether that Anchor is dismissed: true or dismissed: false) — i.e. the Fold-candidate adds nothing the Anchor doesn't already cover, not merely "related" or "similar". If so, recommend Merge into {anchor-slug} instead of Fold. Anchors only absorb — an Anchor is recommended to stay standalone and is not expected to be folded or merged away.

Present a cluster summary as a 3-column table with each child's description and recommendation inline. Output the table as a normal assistant message (not in a code block) so it renders — this message must be sent before calling any interactive question tool:

Cluster: {Display Name} ({N} children, {existing parent | new parent})

Then write 1–2 sentences of reasoning: what the children have in common, whether creating a parent would add meaningful value, and call out any proposed sibling merges.

4b. Ask what to do

Use "What would you like to do with the {Display Name} cluster?" as the question text. Never put (Recommended) on Dismiss. The remaining guidance differs by cluster type:

If parentExists is false (new-parent cluster): Add (Recommended) to Proceed only when the cluster is a clear brand, product line, or named topic with 3+ children that obviously belong under it and at least one child is recommended for folding or merging into a sibling.

Users may also type skip (leave for now; show again next run), review one by one (create parent then decide each child individually), or stop (halt all remaining clusters) in the Other field.

If parentExists is true (existing-parent cluster): Add (Recommended) to Proceed when at least one child is recommended for folding or merging into a sibling.

Users may also type skip (leave for now; show again next run), review one by one (link to parent then decide each child individually), or stop (halt all remaining clusters) in the Other field.

When using an interactive question/options tool, keep the question text short: "What would you like to do with the {Display Name} cluster?" Do not cram the summary, reasoning, or option details into one long question line.

The user must still be able to see the full decision context while choosing: the cluster summary, recommendation reasoning, all four options, and the extra accepted inputs. This context may be in the tool's body/details area, or in an immediately preceding assistant message if that message remains expanded and visible while the dialog is open. If the available question tool cannot keep that context visible together with the options, do not use it for this prompt. Instead, render the summary, reasoning, numbered options, and reply instructions as one normal markdown message, then wait for the user's reply. Accept 1, 2, 3, or 4; also accept skip, review one by one, or stop to halt all remaining clusters.

4c. Collecting and executing decisions

Do not create or edit any files until all decisions are collected. If stop is entered at any point during decision collection, proceed to section 4f without creating any files.

4c.1 If Proceed

Record the 4a table recommendations as final decisions — Fold into the parent, Link (Anchor), or Merge into {anchor-slug} for each child. Proceed to 4c.5.

4c.2 If Link all

Record every dismissed: false child as Link (standalone), overriding any sibling-merge or fold recommendations. dismissed: true children are unaffected — they remain background Anchors. Proceed to 4c.5.