Link Orchestrator

---
name: link-orchestrator
description: Build the directed graph of every internal link on the site, find the missing edges scored by topical similarity, and write exact anchor-text patches — catching the three patterns humans always miss. Use when asked to fix internal linking, audit or map internal links, connect old posts to new ones, link a pillar to its clusters, improve site structure with links, find orphan posts, or someone says 'our posts don't link to each other'. For planning new clusters, see cluster-planner. For applying content edits, see content-refresher.
metadata:
  version: 1.0.0
---

# Link orchestrator

Runs **after every publish, and monthly site-wide.** It builds a directed graph
of every internal link, finds the missing edges scored by topical similarity,
and writes **exact anchor-text patches** — because "you should link these"
without the anchor and the insertion point is advice, and a patch is work done.

It exists because of **the three patterns humans always miss**:

1. **Old posts never link to new ones** — links get added in one direction, at
   publish time.
2. **Pillars do not link down to every cluster** — the pillar predates most of
   its cluster.
3. **Siblings never link across** — nobody thinks to connect two cluster posts.

## Before you start

| Input | Why |
| --- | --- |
| The registry (or sitemap crawl as fallback) | The graph's node list — the registry is the agent's memory of the site |
| Pillar/cluster assignments per post | Edges are scored within topical neighbourhoods |
| The 8–15 links-per-post rule as the budget | Patches respect the band, not just add |
| Approval authority | Patches are proposed; application is approved — see the audit's read-only discipline |

## Step 1 — Build the graph

Nodes: every published URL from the registry. Edges: every internal link,
directed, with its anchor text. Fallback without a registry: crawl the sitemap
— slower, and it still misses the newest posts, which is why the registry
exists.

Immediately visible: **orphans** (no inbound edges), **dead-ends** (no
outbound), and posts outside the 8–15 band in either direction.

## Step 2 — Hunt the three patterns

| Pattern | Query on the graph |
| --- | --- |
| Old → new missing | For each new post: which older, topically-similar posts have no edge to it? |
| Pillar ↓ incomplete | For each pillar: which of its cluster posts lack a pillar-down edge? |
| Siblings unlinked | Within each cluster: which adjacent pairs have no cross edge? |

Score candidate edges by **topical similarity** — a link between unrelated
posts is graph noise, not authority.

## Step 3 — Write the patches, exactly

Each patch is executable, not advisory:

```
| From (URL) | To (URL) | Anchor text (exact) | Insertion point (section/sentence) | Pattern |
```

- Anchor text reads naturally in the sentence it enters — descriptive of the
  target, never "click here".
- **Never invent a URL** — every edge's target comes from the registry. A link
  to a page that does not exist is worse than no link.
- Respect the band: a post already at 15 outbound gets its weakest link
  swapped, not a sixteenth added.

## Step 4 — Propose, approve, apply

Patches go to the operator as the table. Approved patches apply through the
update-by-ID path (same URL, freshness signal) — content-refresher or the
publisher's update mode executes; the orchestrator itself changes nothing.

## Output

```
# Link graph: <site> · <n> nodes, <n> edges

Health: orphans <n> · dead-ends <n> · outside 8-15 band <n>

## Patches by pattern
| From | To | Anchor (exact) | Insert at | Pattern |
[old→new: <n> · pillar↓: <n> · siblings: <n>]

Similarity floor applied: edges below it not proposed
Nothing applied. Approved patches → update-by-ID via content-refresher.
Next run: after next publish · monthly site-wide
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| New posts stay orphans for months | Pattern 1 unpatched — links only added at publish | The old→new hunt is the monthly run's core |
| A proposed link 404s | URL invented instead of registry-read | Every target from the registry, no exceptions |
| Anchor text is "click here" / the bare URL | Anchors written lazily | The anchor describes the target, inside a natural sentence |
| Patches proposed between unrelated posts | No similarity floor | Score edges; below the floor, don't propose |
| A post has 31 outbound links | Band ignored — adding without weighing | 8–15: swap weakest, don't stack |
| Graph misses the newest posts | Built from a crawl, not the registry | The registry is the memory; fix its write step (agent-memory-designer) |
| Patches applied by the orchestrator itself | The propose/apply line crossed | Propose → approve → refresher applies |

Never bulk-apply unapproved patches because they are "obviously right". Sixty
simultaneous unreviewed edits to live posts is how one bad anchor pattern gets
industrialised.

## Rules

- **Every edge target comes from the registry**, because an invented URL breaks
  live and a broken link is worse than a missing one.
- **Patches carry exact anchors and insertion points**, because advice creates
  a to-do list and a patch creates a done-list.
- **Similarity gates every proposal**, because links between unrelated posts
  are noise wearing authority's clothes.
- **The 8–15 band is a budget, both directions**, because link equity dilutes
  past the band and orphans starve below it.
- **Propose, never apply**, because sixty auto-edits to live posts need exactly
  one systematic error to become a site-wide incident.

## Related skills

- **cluster-planner** — plans the map for new clusters; this patches the live
  graph.
- **content-refresher** — applies approved patches via update-by-ID.
- **site-architecture** — the pillar/cluster assignments the scoring uses.
- **agent-memory-designer** — the registry this graph is built from.