taxonomy-builder

Taxonomy Builder (router, compatibility mode)

Triggers & routing

• Trigger: taxonomy, taxonomy builder, classification, topic tree, taxonomy.yml.
• Use when: structural phase of survey/snapshot (NO PROSE), already has papers/core_set.csv, need to generate a mappable and reader-friendly topic structure.
• Skip if: there is already an approved and mappable taxonomy (do not refactor meaninglessly).
• Network: none.
• Guardrail: avoid generic placeholder buckets; keep 2+ levels and each node has a specific description.

Build outline/taxonomy.yml from papers/core_set.csv.

P0 compatibility note:

• The output contract stays the same (outline/taxonomy.yml, YAML list, >=2 levels, concrete descriptions).
• Curated domain taxonomies now live in assets/domain_packs/*.yaml instead of Python prose.
• scripts/run.py stays a deterministic scaffold/helper: detect domain pack -> load pack when available -> otherwise fall back to the generic builder.

Load Order

1. references/overview.md
2. references/taxonomy_principles.md
3. If a domain pack applies, read its references/domain_pack_<domain>.md and assets/domain_packs/<domain>.yaml
4. Otherwise read references/archetypes_generic.md
5. Calibrate naming/description quality with references/examples_good.md and references/examples_bad.md

Current compatibility packs:

• llm_agents
• gen_image
• embodied_ai
• rag_evaluation

Explicit refinement marker

Create outline/taxonomy.refined.ok only after reviewing a manually refined taxonomy. The marker is honored only while it is newer than the taxonomy, its upstream evidence, and the generator; stale markers are removed and the prior taxonomy is backed up before regeneration.

Inputs

• papers/core_set.csv (required)
• Optional: papers/papers_dedup.jsonl
• Optional: DECISIONS.md, GOAL.md, queries.md

Outputs

• outline/taxonomy.yml

Asset contract

• assets/taxonomy_schema.json: machine-readable shape for domain packs / output expectations
• assets/domain_packs/*.yaml: compatibility domain packs for supported domains

Script role

Use scripts/run.py only for deterministic help:

• never overwrite non-placeholder user taxonomy
• preserve current CLI flags / output path
• load a supported domain taxonomy only when GOAL.md / queries.md explicitly match its detection contract
• keep the generic fallback builder for non-packed domains

When to refine manually

Refine the generated taxonomy before marking the unit DONE if:

• top-level buckets feel like keyword clusters instead of chapter-level questions
• leaf names are generic (Overview, Benchmarks, Open Problems, Misc)
• descriptions lack scope cues or representative paper anchors
• domain detection chose the wrong pack

Quick start

• uv run python .codex/skills/taxonomy-builder/scripts/run.py --help
• uv run python .codex/skills/taxonomy-builder/scripts/run.py --workspace <workspace>

Execution notes

When running in compatibility mode, scripts/run.py currently reads:

• papers/core_set.csv as the required corpus input
  • papers/papers_dedup.jsonl when present for generic corpus signals
  • GOAL.md and queries.md as the authoritative domain-pack selection intent; corpus term co-occurrence cannot override them

Script

Quick Start

• uv run python .codex/skills/taxonomy-builder/scripts/run.py --workspace <workspace>

All Options

• --workspace <dir>
• --top-k <int>
• --min-freq <int>
• --unit-id <id>
• --inputs <a;b;...>
• --outputs <a;b;...>
• --checkpoint <C*>

Examples

• uv run python .codex/skills/taxonomy-builder/scripts/run.py --workspace <workspace>

Troubleshooting

• If the wrong domain pack is chosen, inspect GOAL.md, queries.md, and the pack detect rules before changing Python.
• If outline/taxonomy.yml already contains a real non-placeholder taxonomy, the script intentionally returns without overwriting it.
• If no pack matches, the script falls back to the generic builder.