Context
docs/readme_llm/sections/registry_naming_conventions.md.j2 specified a
consolidation of the topic vocabulary from 22 categories down to 7, complete
with scope definitions, naming rules (hyphenated-lowercase, gerunds for
process topics), a migration procedure, and maintenance rules for adding,
merging, splitting and deprecating categories. It also stated the rule that
matters most: each recommendation is tagged with exactly one primary
topic, plus optional secondaries.
It was a decision record in every respect except the ones that make a
decision record useful. It had no number, so nothing could cite it. It lived
in a Jinja template, so it rendered into generated documentation as
description rather than sitting anywhere as a rule. And it was never applied:
at migration time registry.yaml still carried the original 22 topics, and
research.yaml had accumulated 172 distinct topic strings, most used once.
172 strings across 118 papers is not a taxonomy. It includes efficiency
(29 uses) alongside memory efficiency, memory-efficiency and
memory-optimization; inference optimization alongside
inference-optimization; and llama2, which is a model name.
Decision
Apply it, and put each piece where something can check it.
The seven categories are the ones the 2024 document specified, unchanged:
training-optimization, systems-optimization, model-stability,
distributed-optimization, data-pipeline, attention-techniques,
model-architecture. They live in record/practices.d/tags.yaml with the
scopes transcribed from that document.
The one-primary-topic rule becomes a tag_groups constraint in luria.toml
with require = "exactly-one". Secondary tags outside the group stay
unconstrained, as specified.
The LIT scheme gets those seven plus five more —
generative-modeling, vision-and-graphics, adaptation-and-tuning,
inference-optimization, analysis-and-evaluation — because the reading
list covers ground the practice registry does not. Roughly a third of the
corpus is generative, vision or theory work that never produced a training
recommendation, and forcing it into the seven would have meant either a
wrong tag or a category that means nothing.
The mapping from all 172 original strings onto the vocabulary is committed as
data at src/scripts/migration/topic_map.yaml, with the seven papers where
automated scoring read the paper wrong listed individually with reasons. The
original strings survive on every note in a free-form keywords: field, so
the consolidation stays reviewable and nothing is destroyed.
Alternatives considered
- Keep the 172 strings as tags. Honest about what the corpus says, and it produces 172 generated tag pages, most with one entry. A browsing axis with one item per value is not a browsing axis.
- Consolidate but leave the rule in prose. What was tried. The document is well-written and specific and had no effect for two years, which is the evidence.
- Use the seven for both schemes. Simpler to explain, one vocabulary to
learn. It puts a diffusion sampler paper under
training-optimizationormodel-architectureand makes both pages worse. - Derive secondary tags during the import. Tried, and reverted: the
generic strings map somewhere, so Adam came out tagged
model-architecturebecauseneural-networkswas in its topic list. A secondary tag is an editorial judgement the import cannot make.
Consequences
Adding a category is now a config change plus a tags.yaml entry, and the
lint refuses a practice that carries none of the seven or more than one. That
is the intended cost: the vocabulary can no longer drift by accretion, which
is exactly how it reached 172.
The maintenance rules from the 2024 document — merge above 50% scope overlap, split when a category becomes too broad — are not enforceable and are not claimed to be. They stay as guidance, in this decision, where they can at least be cited.