brain-taxonomist

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

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

# Which pages have no type matching the active pack? Counts untyped pages AND
# pages whose type the pack neither declares nor aliases (undeclared_types).
gbrain schema review-orphans --json

# Per-type audit of the stored corpus (stored_type_undeclared / stored_type_is_alias).
gbrain schema lint --with-db --json

Both commands run locally. Over MCP, the run_doctor report carries the same verdict as its schema_pack_consistency check (an undeclared type warns with code page_type_undeclared).

When undeclared types show up, declare them in the pack (gbrain schema add-type <type> --primitive <p> --prefix <dir/>) or rewrite the pages with a declared type. When more than 10% of a source is 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.

**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:

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

When it fails

Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:

• gbrain schema show / gbrain schema lint fails because no schema pack is active or the pack is corrupt: report it and route to the schema-author skill; do not guess a directory from memory.
• A recommendation needs a schema change (gbrain schema add-type, gbrain schema use): this skill is advisory. Hand it to EIIRP or schema-author with the user's agreement; never mutate the active pack from here.

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).