brain-taxonomist

What this skill does

# brain-taxonomist

## Purpose

**Gate function:** Before creating ANY new brain page, consult this skill to determine the correct filing path. This prevents misfiling at write time rather than cleaning up drift after the fact.

**Drift function:** Periodic scan for pages that have outgrown their current location.

## Contract

This skill guarantees:
- Every new page is filed at the path determined by the ACTIVE schema pack — never against a hardcoded directory table baked into this skill.
- The decision is reproducible: invoking brain-taxonomist twice on the same content produces the same recommended path.
- Ambiguous cases surface to the user via `skills/ask-user/` rather than silently picking a default.
- Per-source overrides via `--source <id>` are honored — multi-brain users (Persona B) get a different recommendation per source if their packs diverge.
- When no matching `page_types[]` entry exists in the active pack, the skill signals to EIIRP Phase 3 (SCHEMA CHECK) rather than picking the closest-fitting fallback.

## Critical: this skill reads the ACTIVE schema pack as data

`brain-taxonomist` has NO hardcoded directory table. Every decision is
driven by `gbrain schema show --json`. This means:
- A user who runs `gbrain schema use gbrain-recommended` gets the full
  recommended directory set (deal, meeting, concept, project, source,
  daily, personal, civic, original, place, trip, conversation, writing,
  plus all gbrain-base types).
- A user who authored a custom pack via `gbrain schema init` + edit gets
  filing recommendations based on THEIR taxonomy, not gbrain's defaults.
- Per-source overrides (tier 3 in the 7-tier resolution chain) are honored
  when `--source <id>` is passed to brain-taxonomist.

This is the single-source-of-truth principle (D9 from the v0.39 plan-eng-review).

## When to Consult (MANDATORY)

Run the taxonomist check before writing to the brain in these cases:

1. **New brain page** — any `type` (person, company, concept, book, meeting, etc.)
2. **Bulk import** — before committing a batch of new pages
3. **Uncertain filing** — when the primary subject is ambiguous

You do NOT need to consult for:
- Updating an existing page in place (same path)
- Appending to a Timeline section
- Meeting entity propagation to existing pages

## Decision Protocol

### Step 1: Identify primary subject type

Walk these questions in order:
1. Is the primary subject a NAMED PERSON? → person-typed directory
2. Is the primary subject a NAMED ORGANIZATION? → company-typed directory
3. Is it about a TIME-BOUNDED EVENT (meeting, deal, trip)? → temporal-typed directory
4. Is it a REUSABLE MENTAL MODEL? → concept-typed directory
5. Is it RAW MEDIA (article, video, book, PDF)? → media-typed directory
6. Is it BULK SOURCE DATA? → source-typed directory
7. None of the above → consult EIIRP Phase 3 for schema-pack candidate creation.

### Step 2: Look up the directory for that type in the active pack

```bash
gbrain schema show --json | jq '.page_types[] | select(.primitive == "entity")'
```

Each `page_types[]` entry has a `path_prefixes:` array. The first prefix
is the canonical path. If multiple types match (e.g. both `person` and
`founder` exist in the pack with `expert_routing: true`), prefer the more
specific one (the one with the more specific path prefix).

### Step 3: For books — determine sub-category

The `gbrain-recommended` pack treats books as `media/books/<category>/<slug>.md`
where category is one of: psychology, philosophy, spirituality, business,
media-and-society, family-and-divorce, heritage, science, fiction,
biography, arts-and-design. If your active pack has a different scheme,
walk it from `gbrain schema show --json` instead of hardcoding here.

### Step 4: Construct the slug

- kebab-case, descriptive
- no author name unless disambiguation is needed
- match the canonical path prefix exactly (no leading slash)

### Step 5: Validate before writing

- [ ] Path follows the active pack's `page_types[].path_prefixes`
- [ ] Slug is kebab-case, descriptive
- [ ] Frontmatter includes `type:` matching one of the pack's `page_types[].name`
- [ ] Cross-links to related pages are included

If the active pack doesn't have a type for what you're trying to file,
DON'T pick the closest-fitting one. Instead, signal to EIIRP that a new
type is needed and let the schema-pack cathedral handle the proposal flow.

## Integration with Other Skills

- `eiirp` — calls this skill as Phase 2 TAXONOMY for every output in its inventory.
- `ingest` — article/media ingestion consults brain-taxonomist for filing.
- `repo-architecture` — delegates the filing decision to this skill.
- `book-mirror` — after generating a mirror, files it via brain-taxonomist.

## Periodic Drift Detection

```bash
# What pages have no type matching the active pack?
gbrain schema review-orphans --json

# What's the overall health?
gbrain doctor --json | jq '.checks[] | select(.name == "schema_pack_consistency")'
```

When `schema_pack_consistency` warns at >10% untyped, run the EIIRP
Phase 3 SCHEMA CHECK flow to surface candidate types via `schema detect`.

## Output Format

Advisory: a single recommendation block plus a one-line reasoning trail.

```markdown
**File at:** `<directory>/<slug>.md`
**Reasoning:**
- Primary subject: <person|company|concept|...>
- Matched page_type: <name> (primitive: <entity|temporal|concept|media|annotation>)
- Active pack: <pack-name> v<version>
- Source: <source_id>
```

When ambiguous, surface 2 candidates via `skills/ask-user/` rather than
silently choosing.

When the active pack has NO matching type, signal to EIIRP Phase 3
(SCHEMA CHECK) and emit:

```markdown
**No match in active pack `<name>`.**
**Suggested next step:** `gbrain schema detect --source <source_id>` then
`gbrain schema review-candidates`.
```

## Anti-Patterns

- **Hardcoded directory table in this skill.** Every decision goes through
  `gbrain schema show --json`. v0.39+ broke the old hardcoded table on
  purpose so users on `gbrain-recommended` or custom packs get the right
  routing automatically.
- **Picking the closest-fitting type when no type matches.** Closest-fit
  silently degrades user filing. Surface to EIIRP Phase 3 instead.
- **Ignoring `--source <id>` on multi-brain setups.** Per-source overrides
  are tier-3 in the 7-tier resolution chain; missing the flag silently
  uses the brain-wide active pack.
- **Auto-applying a `gbrain schema review-candidates --apply` decision.**
  Even high-confidence suggestions need user approval — this skill is a
  GATE, not an automator.

## Hard Rules

- **Never hardcode a directory table in this skill.** Every decision goes
  through `gbrain schema show --json`. The active pack is canonical.
- **Per-source flag is first-class.** Pass `--source <id>` to every CLI
  call when working with a non-default source.
- **Confidence-floor honor.** EIIRP's Phase 3 produces suggestions with
  confidence < 0.6 that brain-taxonomist must surface to the user rather
  than auto-apply. Don't silently promote a low-confidence schema delta.

## Changelog

### v1.0.0 — gbrain v0.39.0.0
- Initial port from upstream OpenClaw. Genericized — no references to
  private fork names per CLAUDE.md privacy rules.
- Hardcoded directory table REMOVED. Every decision now reads the active
  schema pack via `gbrain schema show --json`. Single source of truth.
- Book taxonomy moved from skill-text to the `gbrain-recommended` pack's
  media/books/ branch (see `src/core/schema-pack/base/gbrain-recommended.yaml`).
- `--source <id>` propagation documented for multi-brain users (Persona B).