Skip to main content

Tag Taxonomy

How does a tag earn the right to steer the map?

Tags are the faceted control plane for playbook navigation. They feed generated projections such as the domain matrix, so a loose tag is not harmless metadata. It changes the map a reader or agent uses to decide where knowledge lives.

Rule​

Use atomic concept tags.

  • A tag must be one token with no spaces.
  • Prefer one word when the concept survives as one word.
  • Use a hyphenated token only when the whole phrase is one concept, such as real-estate, feedback-loop, or information-architecture.
  • Reuse the canonical vocabulary before creating a new tag.
  • Never rely on a tool to silently rewrite tags. A validator should flag and block bad tags, then the writer chooses the correction.

Vocabulary​

The machine-readable source is src/data/playbook-navigation/tag-vocabulary.json.

That file carries:

  • canonical — the allowed explicit frontmatter tag list.
  • aliases — old or invalid spellings used only for error messages and reviewed migrations.
  • rule — the locked rule, currently atomic-concept-no-spaces.

The vocabulary seed came from the explicit post-migration playbook tag corpus. It is intentionally a seed, not a final ontology. Future cleanup should collapse weak one-off tags into stronger concepts only when the affected pages make that meaning clear.

Enforcement​

Two gates read the same vocabulary.

  • scripts/artifacts/validate-playbook-tags.mjs checks explicit playbook frontmatter tags.
  • scripts/artifacts/generate-playbook-manifest.mjs refuses to regenerate projections when explicit tags violate the vocabulary.

The pre-commit hook calls the validator for staged playbook files. The generator gate protects non-commit paths and CI checks.

Operating Pattern​

Use the tag system as a deliberate navigation tool, not as decoration.

Do this when a page needs a retrieval facet:

  1. Read nearby pages before adding or changing a tag.
  2. Choose the smallest canonical concept that would help a reader filter the corpus.
  3. Add the tag to frontmatter only when it improves retrieval across more than one page.
  4. Run the tag validator before regenerating projections.
  5. Update this page when the rule changes, not when one synonym changes.

Failure Modes​

A weak tag makes the map noisier.

  • Phrase tags split one concept across several spellings.
  • Page-title tags create one-off facets that never help navigation.
  • Route-derived tags hide whether a page has deliberate taxonomy or inherited location.
  • Silent rewrites make the corpus look clean while hiding author intent.
  • Aliases that never collapse into canonical tags become a second vocabulary.

Adding A Tag​

Add a new tag only when all four checks pass.

  1. Existing tags do not already express the concept.
  2. The tag names a reusable facet, not a one-page title.
  3. The tag is one token with no spaces.
  4. The tag is added to the vocabulary in the same change as the page that uses it.

If the concept is a page-level idea rather than a navigation facet, write or link the page instead of minting a tag.

Context​

Questions​

Which current one-off tags should be retired because they are page titles pretending to be facets?

  • Which tags deserve promotion into high-signal domain projections?
  • Which aliases keep appearing and therefore point to a missing canonical concept?