agent-wiki-consolidate-guidelines

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).