skos-taxonomy

What this skill does

# SKOS Taxonomist

Design operational taxonomies with SKOS so Panda and all sub-agents classify work consistently, retrieve better context, and avoid tag soup.

This skill is for execution, not theory: define concepts, classify agent data, validate constraints, and wire taxonomy fields into Typesense.

## When to Use

Use this skill when any request involves:

- "taxonomy", "SKOS", "controlled vocabulary", "concept scheme"
- classifying agent interactions, runs, docs, memory, events, or tasks
- designing or revising `concept_ids` / `primary_concept_id` contracts
- mapping joelclaw concepts to another vocabulary
- deciding whether SKOS is needed or a simpler tag model is enough

## Primary Outcomes

1. A versioned SKOS concept scheme with stable concept URIs.
2. Agent-classification rules that produce deterministic concept metadata.
3. Typesense field mappings that support lexical, faceted, and hybrid retrieval.
4. Governance rules for candidate concepts, alias drift, deprecation, and mappings.

## Non-Negotiable SKOS Rules (Normative)

Follow these in every scheme:

1. `skos:Concept` and `skos:ConceptScheme` are distinct classes.
2. `skos:broader` is **not** transitive; use transitive super-property semantics (`skos:broaderTransitive`) for closure queries.
3. `skos:prefLabel` max one value per language tag for a resource.
4. `skos:prefLabel`, `skos:altLabel`, and `skos:hiddenLabel` are pairwise disjoint for the same resource+language form.
5. `skos:related` is disjoint with `skos:broaderTransitive`.
6. Mapping relations are for cross-scheme linking. `skos:exactMatch` is transitive and should be used sparingly.
7. `skos:closeMatch` is intentionally non-transitive.
8. `skos:Collection` / `skos:OrderedCollection` are for grouping; they are disjoint with `skos:Concept`.

If any of these fail, stop and fix data before rollout.

## JoelClaw Operational Scheme (Workload v1)

Define a dedicated scheme for workload classification:

- Scheme URI: `joelclaw:scheme:workload:v1`
- Taxonomy version string: `workload-v1`
- Concept URI pattern: `joelclaw:concept:<top-level>[:<subconcept>]`
- Notation style: upper snake or dotted operational codes (stable and immutable)

### Top-Level Concepts (Required)

| Notation | URI | Purpose |
|---|---|---|
| `PLATFORM` | `joelclaw:concept:platform` | Runtime/platform infrastructure and hosting substrate |
| `INTEGRATION` | `joelclaw:concept:integration` | External system connections, APIs, webhooks, adapters |
| `TOOLING` | `joelclaw:concept:tooling` | CLI/dev tooling, operator commands, local automation |
| `PIPELINE` | `joelclaw:concept:pipeline` | Inngest/event workflows, ingestion and processing chains |
| `BUILD` | `joelclaw:concept:build` | Code implementation, tests, CI/CD, packaging |
| `KNOWLEDGE` | `joelclaw:concept:knowledge` | Docs, memory, taxonomy, retrieval context |
| `COMMS` | `joelclaw:concept:comms` | Messaging channels, notifications, agent/user communication |
| `OBSERVE` | `joelclaw:concept:observe` | OTEL/logging/metrics/diagnostics/reliability telemetry |
| `META` | `joelclaw:concept:meta` | Governance, ADRs, policies, lifecycle and process controls |

### Core Turtle Skeleton

```turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:scheme:workload:v1 a skos:ConceptScheme ;
  skos:prefLabel "JoelClaw Workload Taxonomy v1"@en ;
  skos:definition "Operational workload taxonomy for Panda and sub-agents."@en ;
  skos:hasTopConcept
    jcw:concept:platform,
    jcw:concept:integration,
    jcw:concept:tooling,
    jcw:concept:pipeline,
    jcw:concept:build,
    jcw:concept:knowledge,
    jcw:concept:comms,
    jcw:concept:observe,
    jcw:concept:meta .

jcw:concept:pipeline a skos:Concept ;
  skos:inScheme jcw:scheme:workload:v1 ;
  skos:topConceptOf jcw:scheme:workload:v1 ;
  skos:notation "PIPELINE" ;
  skos:prefLabel "Pipeline"@en ;
  skos:altLabel "workflow"@en, "event flow"@en ;
  skos:definition "Durable event-driven processing sequences."@en ;
  skos:scopeNote "Use for Inngest functions, ingest chains, and orchestration logic."@en ;
  skos:narrower jcw:concept:pipeline:ingest, jcw:concept:pipeline:enrichment ;
  skos:related jcw:concept:observe, jcw:concept:build .
```

## Agent Classification Contract

Every sub-agent output that can be stored/retrieved must emit:

- `primary_concept_id` (single canonical concept URI)
- `concept_ids` (ordered list: primary first, then secondary)
- `taxonomy_version`
- `concept_source` (`rules|llm|backfill|manual|fallback`)
- `classification_confidence` (0-1 float, optional but recommended)

Recommended envelope:

```json
{
  "primary_concept_id": "joelclaw:concept:pipeline:ingest",
  "concept_ids": [
    "joelclaw:concept:pipeline:ingest",
    "joelclaw:concept:knowledge",
    "joelclaw:concept:observe"
  ],
  "taxonomy_version": "workload-v1",
  "concept_source": "rules",
  "classification_confidence": 0.88
}
```

### Classification Procedure

1. Normalize candidate labels (`trim`, lowercase, slugify, punctuation collapse).
2. Match against `prefLabel`, then `altLabel`, then `hiddenLabel` alias tables.
3. Disambiguate using `scopeNote` and neighboring concepts (`broader`, `related`).
4. Emit one primary concept plus optional secondary concepts.
5. If unresolved, map to a controlled fallback concept and log unmapped labels.
6. Emit OTEL metadata for mapping diagnostics (`mapped_count`, `unmapped_count`, `taxonomy_version`).

## SKOS-XL (When Labels Need First-Class Metadata)

Use SKOS-XL only when label objects need metadata or relationships:

- acronym/abbreviation management with provenance
- per-label source attribution
- multilingual/transliteration workflows with label-level auditing
- label-to-label relationships (deprecated term -> replacement term)

If labels are plain synonyms only, stay with core SKOS labels.

### SKOS-XL Example

```turtle
@prefix skosxl: <http://www.w3.org/2008/05/skos-xl#> .
@prefix jcw: <joelclaw:> .

jcw:label:comms:imessage a skosxl:Label ;
  skosxl:literalForm "iMessage"@en .

jcw:concept:comms:imessage skosxl:altLabel jcw:label:comms:imessage .
```

## Mapping to External Vocabularies

Use mapping properties across schemes, not inside one scheme:

- `skos:exactMatch`: interchangeable meaning (rare, high bar)
- `skos:closeMatch`: near-equivalent, safe default for most interop
- `skos:broadMatch` / `skos:narrowMatch`: granularity mismatch
- `skos:relatedMatch`: associative cross-scheme link

### Internal Cross-Scheme Example (Workload -> Existing Docs Scheme)

```turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .
@prefix jcd: <jc:> .

jcw:concept:build skos:closeMatch jcd:docs:programming .
jcw:concept:observe skos:broadMatch jcd:docs:operations .
jcw:concept:knowledge skos:relatedMatch jcd:docs:education .
```

Mapping guardrails:

1. Start with `closeMatch`; escalate to `exactMatch` only with explicit review.
2. Do not chain `exactMatch` blindly across multiple schemes.
3. Review inferred collisions caused by transitive/symmetric mapping behavior.

## Collections and Ordered Collections

Use collections for non-hierarchical grouping:

- `skos:Collection` for thematic bundles (example: all communication channels)
- `skos:OrderedCollection` for deterministic sequences (example: escalation stages)

Do not encode hierarchy with collections. Use `broader`/`narrower` for taxonomy structure.

```turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:collection:comms-channels a skos:Collection ;
  skos:prefLabel "Comms channels"@en ;
  skos:member
    jcw:concept:comms:telegram,
    jcw:concept:comms:slack,
    jcw:concept:comms:imessage .
```

## URI and Notation Policy (`joelclaw:`)

1. URI local parts are lowercase kebab or colon-separated operational paths.
2. `skos:notation` is immutable once released.
3. Never repurpose a concept URI. Deprecate old URI and add mappings.
4. Keep human names in labels, not in IDs.