2. Update Taxonomy Rules

Purpose: Update per-topic extraction guidance, vocabulary, voice, or avoidance patterns that shape how facts are extracted and categorized. The taxonomy has 1,104 active categories across 33 roots and 4 depth levels (0-3). Subcategories without their own rules/voice entry inherit from the nearest ancestor that has one.

Prerequisites:

  • Bun installed with bun install completed
  • Familiarity with the taxonomy content rules system
  • Know the target category's slug and depth (query topic_categories if unsure)

Cost / Duration: $0 | 15-30 minutes

Prompt

Update taxonomy rules for the Eko fact extraction system.

I need to change: [describe what you want to update, e.g.,
"add domain terms for the Science category",
"update voice pitfalls for History",
"add prefer-over substitutions for Technology"]

Step 1 — Edit the relevant taxonomy TypeScript data files:

Depending on what you are changing, edit one or both of:

- `packages/ai/src/config/taxonomy-rules-data.ts`
  Contains per-topic extraction rules, avoidance patterns,
  domain-specific terminology, expert-level phrasing,
  and vocabulary preferences (use X instead of Y).
  Keyed by category slug (any depth). 33 roots + subcategory
  overrides.

- `packages/ai/src/config/taxonomy-voices-data.ts`
  Contains per-topic voice instructions and common voice
  mistakes (pitfalls) per topic.

Edit the TypeScript data directly. Each file exports typed
constants -- follow the existing entry shapes when adding or
modifying entries.

Note: Subcategories inherit rules/voice from the nearest
ancestor that has an entry. Adding an entry for a subcategory
slug overrides the inherited rules for that node and its
descendants. Use the schema coverage audit
(`bun scripts/taxonomy/audit-schema-coverage.ts <slug>`) to
identify subcategories with missing own entries (ownership gaps).

Step 2 — Verify TypeScript compiles:

```bash
bun run typecheck
```

Step 3 — Run taxonomy drift tests:

```bash
bunx vitest run packages/ai/src/drift/__tests__/taxonomy-drift.test.ts
```

This validates that the updated taxonomy rules pass semantic
drift checks and do not conflict with existing invariants.

Step 4 — Run full drift suite (recommended):

```bash
bunx vitest run packages/ai/src/drift/__tests__/
```

Key references:
- Taxonomy rules data: `packages/ai/src/config/taxonomy-rules-data.ts`
- Taxonomy voices data: `packages/ai/src/config/taxonomy-voices-data.ts`
- Taxonomy content rules logic: `packages/ai/src/taxonomy-content-rules.ts`
- Categories: `packages/ai/src/config/categories.ts`

Verification

  • Taxonomy data file(s) updated with new entries
  • bun run typecheck passes
  • Taxonomy drift tests pass with no regressions
  • Full drift suite passes
  • No duplicate keys in prefer-over or domain-terms entries
  • If adding a subcategory entry, verify it overrides the correct ancestor (check with --depth=1 audit)

Back to index