agent-wiki-consolidate-guidelines

name	agent-wiki-consolidate-guidelines
description	Read all atomic guidelines in wiki-twobatch/guidelines/ and propose themed clusters that group near-duplicates. Writes cluster pages and updates _config.yaml; originals are preserved with a `superseded_by:` backref.

Agent Wiki — Consolidate Guidelines

Overview

Spot duplicates and recurring themes across the corpus of atomic guidelines. Author cluster pages that aggregate related variants and record the membership in _config.yaml. Originals stay — clusters reference them; nothing is moved or merged.

This is the cross-trajectory pattern-recognition pass of the agent-wiki family. Run it after one or more extract-guidelines sessions when the wiki has accumulated enough atomic guidelines that a theme is visible.

When to run

• After a batch of extract-guidelines runs, when you suspect duplicates.
• When guidelines/index.md's "By tag" section has 3+ entries under the same tag and you want a canonical aggregator page for that theme.
• When users complain that recall returns N near-identical hits.

Workflow

Step 1: Read the corpus

uv run python explorations/agent-wiki/skills/scripts/build_agent_wiki.py dump-guidelines > /tmp/guidelines.json

Output is a JSON array of {id, filename, title, trigger, cluster, is_cluster_page, content} for every page in guidelines/. The is_cluster_page flag tells you which entries are existing aggregators (__cluster.md suffix) — you will be adding new clusters, not re-deriving existing ones.

Read the file:

Read /tmp/guidelines.json

Step 2: Decide groupings

For each candidate cluster:

• Theme: a one-line statement of the shared idea ("when system EXIF tools are missing, parse JPEG bytes directly with stdlib").
• Members: 2–6 atomic guideline ids that share that theme. Atomic only — never include is_cluster_page: true entries.
• Tags: 2–4 short tags that describe the theme.

Rules:

1. Don't cluster unrelated guidelines just to clean up the listing. A cluster needs a real shared rule, not a shared topic.
2. Don't merge content across atomic pages. Each atomic page stays whole. The cluster's body summarizes the theme and links to members.
3. Don't propose a cluster for a single guideline. Wait for ≥2 members.
4. Don't re-author an existing cluster unless members materially changed. Skip clusters that already exist with the same membership (existing_clusters field below).

Step 3: For each new cluster, output JSON

{
  "slug": "exif-stdlib-fallback",
  "title": "EXIF stdlib parser fallback",
  "description": "1-2 paragraphs framing the shared theme.",
  "takeaway": "1 paragraph: the actionable rule the cluster captures.",
  "members": ["04474b0794e6", "de04f5adde2e", "4746bf445108"],
  "tags": ["exif", "stdlib", "fallback"]
}

Pipe to:

echo '<json>' | uv run python explorations/agent-wiki/skills/scripts/build_agent_wiki.py render-cluster

The helper:

• Updates wiki-twobatch/_config.yaml clusters.<slug> entry.
• Writes guidelines/<slug>__cluster.md with priority: high, member links, snippets pulled from disk.

Step 4: Refresh indexes

After writing all new cluster pages:

uv run python explorations/agent-wiki/skills/scripts/build_agent_wiki.py catalog

catalog propagates the cluster membership back to atomic pages: each member gets cluster: <slug>__cluster.md and superseded_by: <slug>__cluster.md in its frontmatter, and the cluster page is re-rendered against current member content.

Best practices

1. Write the takeaway first. If you can't articulate one shared rule in a sentence, the cluster doesn't exist.
2. Be conservative. Two false-positive clusters cost more than two un-clustered duplicates.
3. Preserve atomic provenance. A reader should be able to navigate cluster → member → source trajectory in two clicks.
4. Don't re-cluster within an existing cluster. Sub-themes don't justify nesting.
5. Always tail-call catalog after the cluster loop.