What problem does it solve? Structural changes to a documentation corpus—adding a kind, facet, shelf, relation, identifier scheme, or obligation—fail silently or get refused by headwater new when taxonomy declarations are missing, misplaced, or left unresolved. This Skill guides you through proposing, validating, and resolving taxonomy changes so every check sees a consistent lock. ## Core Features & Use Cases - Declaration Placement: Routes each declaration to the correct source among taxonomy-source/, docs/taxonomies/ bundles, and .headwater/overlay.yml, at the widest scope where it is true. - Validate-Resolve Workflow: Enforces the order headwater taxonomy validate then headwater taxonomy resolve, since headwater check reads only the lock and never the sources. - Validator Rule Guidance: Explains kind rigidity, facet ascertainability, and volatility permanence rules, plus the judgments no validator can make (kind vs. facet, shelf overlap, purpose, edge ownership). - Use Case: When headwater new refuses to scaffold a document because its kind lacks an identifier scheme, use this Skill to add the scheme to the right bundle, validate, resolve, commit the lock, and re-record fixtures. ## Quick Start Ask the assistant to add a new document kind to the taxonomy, then have it run headwater taxonomy validate, resolve, and audit before committing the lock.
