---
name: knowledge-taxonomy
description: Manage the 3-level taxonomy used to classify wiki articles. Customizable via vault override + agent proposal flow.
allowed-tools: update_taxonomy
title: Knowledge Taxonomy
category: _meta
status: active
metadata:
  triggers:
  - taxonomy
  - organize knowledge
  - wiki structure
  - classify articles
  - knowledge categories
---
## Instructions

You manage the knowledge taxonomy — the 3-level hierarchical classification system that organizes every wiki article into one primary path.

### Structural Contract (load-bearing)

The taxonomy has **exactly three levels**. The page title is NOT a level.

- **Level 1** — top-level domain. The 7 Level-1 slugs are FIXED:
  `areas`, `projects`, `knowledge`, `entities`, `sources`, `workflows`, `reference`.
  The schema rejects an 8th — they are architectural.
- **Level 2** — major area or object class.
- **Level 3** — specific subcategory.

Path format: slug-based, lowercase-hyphenated ASCII (e.g. `areas/self/health`). Each page has exactly ONE primary `taxonomy_path` in its frontmatter.

### Customization Layers

Resolution order, low to high precedence:

1. **Bundled defaults** at `config/taxonomy.yaml` (this skill folder). Shipped with the wheel — should be treated as read-only by users.
2. **Vault override** at `<vault>/agntspace/system/skills/_meta/knowledge-taxonomy/config/taxonomy.yaml`. Partial — define only the L2/L3 nodes you want to add or override, keyed by slug. The loader merges by slug; descriptions and names override bundled when non-empty.
3. **Pending proposals** at `<vault>/agntspace/memory/pending/taxonomy-proposals/<id>.json`. Awaits user approval before merging into the override file.

The L1 lock applies to overrides too — adding a new Level-1 slug in the vault override is silently filtered out. Only L2/L3 nodes can be added.

### When To Propose a New Node

Use the `update_taxonomy` tool with `action: "propose_node"` when one of these triggers fires:

1. **Recurring unclassified bucket** — three or more articles in the last 7 days landed in the unclassified path with a shared theme. Example: 5 articles about industrial robotics and no `knowledge/technology/robotics` node — propose it.
2. **User asks** — explicit request like "add a Machine Learning subcategory under Technology". Translate to the right path and propose.
3. **Domain shift** — the user starts working in a new domain and the existing tree doesn't have the L2/L3 to host it cleanly.

### When NOT To Propose

- Don't propose an L1. The fixed set is architectural — `archive`, `inbox`, etc. are off-limits.
- Don't propose a node that already exists in the merged tree. Use `action: "get_status"` first if uncertain.
- Don't propose for one-off articles. Two articles isn't a pattern; it's a coincidence.
- Don't propose during ingest. Wait until the article is classified, then look at fallback patterns weekly.

### Tool Use

`update_taxonomy(action: "propose_node", node: {...})` — sends a proposal to the pending queue. The node payload:
- `path` — slug-based 2- or 3-segment path (e.g. `"knowledge/technology/robotics"`)
- `name` — display name
- `description` — one-line purpose, used in classify prompts
- `rationale` — why this node is needed (1-3 sentences, concrete)
- `examples` — optional array of article slugs/titles that would file here

`update_taxonomy(action: "list_pending")` — return pending proposals. The user reviews them in the UI / approves/rejects.

`update_taxonomy(action: "get_status")` — return merged-tree counts (L1/L2/L3 totals) plus pending proposal stats. Use to check for duplicates before proposing.

### Classification Rules (when filing an article)

1. **Read the merged taxonomy** — never assume only the bundled defaults; the user's vault override may have added domain-specific nodes.
2. **Match by entity_type first** — people → `entities/people`, organizations → `entities/organizations`, source summaries → somewhere under `sources/`.
3. **Match by content second** — read the article's title + summary and find the most specific leaf node whose description fits.
4. **Prefer depth** — classify to the most specific (L3) matching node when one exists; otherwise use the L2 parent.
5. **Empty path is fine** — if nothing fits, leave `taxonomy_path` empty. The unclassified bucket is the right home for genuinely unclassifiable content. Don't force a fit.

## Rules

- Each article belongs to exactly one taxonomy_path. Cross-cutting goes in tags / links / frontmatter — never duplicate paths.
- Never propose Level-1 changes. The 7 are fixed.
- Three levels max. The page title is not a level.
- Slugs must be lowercase ASCII, hyphen-separated, no leading/trailing hyphen.
- Proposals require user approval — the agent never silently mutates the override file.
- A description is mandatory for every proposed node. It guides the next classification call and the LLM picks the wrong target without it.