---
name: taxonomy-orphan-detect
description: Engine substrate for the heartbeat-driven detector that finds clusters of articles classified into undeclared taxonomy paths and proposes the missing nodes for user approval.
title: Taxonomy Orphan Detector
category: _meta
status: active
author: agentic
metadata:
  priority: 4
---
## Purpose

Closes the eyes-mouth gap in AgntSpace's taxonomy evolution loop. The
philosopher agent already has the *mouth* (`update_taxonomy(action="propose_node", ...)`)
that writes proposals to the user-approval queue. This skill defines
the *eyes*: a heartbeat-driven scan that detects when articles cluster
on `taxonomy_path` values the YAML tree doesn't know about, and
automatically fires proposals.

**Without this skill** the proposal mechanism only fires when a user
explicitly asks "propose a new taxonomy node" in chat. With it, the
agent surfaces these gaps proactively — exactly mirroring the
existing ontology auto-evolution loop (3+ `related_to` fallbacks → new
predicate proposal) and trust-domain auto-discovery loop.

## When this fires

The detector walks every wiki article's `taxonomy_path` frontmatter.
For each path, it identifies the deepest YAML-known ancestor and the
first orphan segment after it. Articles whose orphan segment matches
across ≥ `min_cluster_size` (default 5) become a single proposal.

Examples on a fresh vault:
- 19 articles classified into `knowledge/risk-safety` → proposes a
  new L2 node "Risk Safety" under "Knowledge"
- 12 articles into `knowledge/humanities` → proposes "Humanities"
- 179 articles into `knowledge/general` (from path-inference fallback)
  → proposes "General" as a catch-all under "Knowledge"

## What it doesn't do

- **Never proposes new L1 nodes.** The L1 set is locked at 7 buckets
  by `FIXED_L1_SLUGS`. Articles with paths starting outside the locked
  set are ignored (they'd need a different fix).
- **Never approves anything.** Proposals land in the pending queue.
  The user reviews via `/api/wiki/taxonomy/proposals`.
- **Never re-proposes a path with an active pending proposal.** Stable
  ids ensure idempotency — re-running on a vault with no changes is
  a no-op.
- **Never waits on LLM.** Pure frontmatter scan + path math. Cheap
  enough to run daily.

## Output format

For each cluster ≥ threshold, the detector writes one proposal to:

```
<vault>/agntspace/memory/pending/taxonomy-proposals/prop-<sha8>.json
```

The proposal carries:
- `path`: the proposed L2 or L3 path
- `name`: human-friendly name from the orphan slug
- `description`: auto-generated (count + detector source)
- `rationale`: explains the cluster + 3 sample titles
- `proposed_by: "taxonomy-orphan-detector"`
- `examples`: up to 3 sample article titles

## Tuning knobs (config/orphan.yaml)

- `enabled` (bool, default true) — gate the whole detector
- `min_cluster_size` (int, default 5) — minimum articles for a proposal
- `sample_titles_count` (int, default 3) — how many titles to attach
- `skip_if_pending` (bool, default true) — dedup vs in-flight proposals
- `cadence_hours` (int, default 24) — heartbeat interval

Edit YAML, restart server, no code change. (Rule 12: strategy lives in
skills, not in code.)