Taxonomy Builder

Turn a core paper set into a 2+ level, mappable taxonomy that will drive the outline and paper-to-section mapping.

This is structure, not writing: avoid prose paragraphs and avoid “generic placeholder” buckets.

Role cards (prompt-level guidance)

• •

  Taxonomy Architect

  • •Mission: create a taxonomy that reads like a survey’s core chapters (few, thick buckets).
  • •Do: choose 3–4 top-level chapters by reader questions and decision-relevant axes.
  • •Avoid: keyword-only clusters, “Misc/Other”, and too many top-level buckets that would bloat the final ToC.
• •

  Mapping Sponsor

  • •Mission: keep the taxonomy mappable to real papers.
  • •Do: ensure each leaf can plausibly map to multiple papers (ideally ≥3); keep node names discriminative.
  • •Avoid: overlapping buckets whose boundaries are not explainable.
• •

  Scope Guardian

  • •Mission: encode what counts as in-scope at the taxonomy level.
  • •Do: bake boundary cues into descriptions (what belongs here, what does not).
  • •Avoid: relying on later prose to resolve scope drift.

When to use

• •You have a papers/core_set.csv and need a stable structure for a survey/snapshot.
• •You want categories that are meaningful to readers (not just keyword clusters).

When not to use

• •You already have an approved taxonomy that maps well to your target narrative (don’t churn it).

Inputs

• •papers/core_set.csv (required)
• •Optional: papers/papers_dedup.jsonl (to peek at abstracts/metadata)
• •Optional: DECISIONS.md (scope constraints)

Output

• •outline/taxonomy.yml

Workflow (heuristic)

Uses: papers/papers_dedup.jsonl, DECISIONS.md.

1. •Skim the core set and cluster by reader-relevant axes, not by surface keywords.
   • •For LLM agents, common axes: control loop/architecture, tool use, planning & reasoning, memory/RAG, multi-agent coordination, evaluation/benchmarks, safety/security, applications.
2. •Choose top-level nodes that feel like “chapters in a survey”, and keep a paper-like section budget:
   • •If you want a paper-like PDF with ~6–8 H2 sections total (see ref/agent-surveys/STYLE_REPORT.md), remember the pipeline also adds fixed H2 sections (Introduction / Related Work / Discussion / Conclusion).
   • •In that case, aim for ~3–4 taxonomy-driven chapters (top-level nodes), not 8–12 tiny buckets.
   • •Deep surveys can go wider (e.g., 5–6 taxonomy chapters), but expect thinner writing unless you also expand evidence and writing budgets.
3. •For each top-level node, create 2–6 subtopics with clear inclusion cues (what belongs here, what doesn’t).
4. •Write a short description for every node:
   • •define what the bucket covers
   • •name 2–5 representative paper IDs (or recognizable lines of work) that belong here
5. •Sanity check:
   • •leaves aren’t too tiny (ideally ≥3 papers per leaf)
   • •names are mutually exclusive enough (some overlap is OK, confusion is not)

Quality checklist

• • outline/taxonomy.yml has ≥2 levels.
• • Every node has a description with concrete meaning (not “Papers and ideas centered on …” boilerplate).
• • Leaf nodes look mappable (not overly broad like “Misc/Other”).
• • Top-level nodes feel like chapters (avoid too many tiny buckets if you target a paper-like 6–8 H2 structure).

Common failure modes (and fixes)

• •Generic buckets (“Overview/Benchmarks/Open Problems”) → rename to content-based subtopics.
• •Keyword clustering → reframe as design/evaluation questions a reader would ask.
• •Too much overlap → tighten inclusion cues; split a bucket by mechanism vs evaluation vs safety.
• •Too many top-level buckets → merge into fewer, thicker chapters; push fine-grained points into subsection bullets/axes instead of new H2 sections.

Helper script (optional)

Quick Start

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

All Options

• •--top-k <n>: number of candidate terms to consider
• •--min-freq <n>: minimum frequency threshold

Examples

• •Generate a baseline taxonomy (then optionally refine):
  • •python .codex/skills/taxonomy-builder/scripts/run.py --workspace <ws> --top-k 100 --min-freq 2

Notes

• •The script generates a baseline 2-level taxonomy (topic-aware) and never overwrites non-placeholder work.
• •In pipeline.py --strict it will be blocked only if placeholder markers (TODO/TBD/FIXME/(placeholder)) remain.

Refinement marker (recommended; completion signal)

When you are satisfied with the taxonomy (and after C2 approval if applicable), create:

• •outline/taxonomy.refined.ok

This is an explicit "I reviewed/refined this" signal:

• •makes it harder for a scaffold-y taxonomy to silently pass in strict runs
• •documents that buckets were edited into reader-meaningful, mappable nodes

Troubleshooting

Common Issues

Issue: Quality gate blocks taxonomy_scaffold

Symptom:

• •output/QUALITY_GATE.md reports taxonomy contains TODO/placeholder text.

Causes:

• •Helper script generated a scaffold, but taxonomy was not rewritten.

Solutions:

• •Rewrite every node name + description to be domain-meaningful.
• •Ensure ≥2 levels via children.
• •Remove generic buckets like “Overview/Benchmarks/Open Problems”.

Issue: Taxonomy has no depth (children missing)

Symptom:

• •Quality gate reports “needs ≥2 levels”.

Causes:

• •Only top-level nodes were created.

Solutions:

• •Add 2–6 child nodes per top-level node, each with clear inclusion cues.

Recovery Checklist

• • outline/taxonomy.yml is valid YAML list.
• • At least one node has a non-empty children list.
• • No TODO/(placeholder) remains.