# Derive Taxonomy

> Derive product-domain taxonomy from change intents and existing specs, producing nested domain/context/capability boundaries.

- Skill: `shanepadgett/derive-taxonomy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shanepadgett/derive-taxonomy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shanepadgett/derive-taxonomy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shanepadgett (https://skillmd.com/u/shanepadgett)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/shanepadgett/derive-taxonomy

---


# Derive Taxonomy

## Purpose

Translate change intents into a product-domain taxonomy by:

- understanding existing domain and capability structure,
- evaluating boundary quality,
- proposing nested domain/context/capability paths,
- and producing final capability spec filenames.

Taxonomy derivation must explicitly surface all needed scope across the tree:

- new capabilities under existing domains,
- existing capabilities that likely need modification,
- entirely new domains/contexts when current taxonomy does not fit,
- with nesting depth allowed to grow to any number of levels based on product boundaries.

The taxonomy must stay implementation-agnostic and product-boundary first.

## Inputs I need

- Change intent(s) or proposal text.
- Relevant context about existing domains and capabilities.
- Canonical/change-set spec structure when available.

## Workflow

1. Load the `research` skill and inspect existing specs/taxonomy artifacts first.
2. Build an **Existing Taxonomy Snapshot**:
   - list discovered domains/subdomains/capabilities,
   - identify strong boundaries,
   - flag ambiguous or missing boundaries.
3. Decompose the change intent into product concerns:
   - actors,
   - workflows,
   - business rules/invariants,
   - capability outcomes.
4. Propose a **nested taxonomy tree** using:
   - `Domain -> Subdomain/Context -> Capability Leaf`
   - nesting depth is unbounded and may go to any number of levels when each level introduces a distinct product boundary.
5. Convert the proposed tree into concrete taxonomy artifacts:
    - folder paths,
    - capability leaf names,
    - and spec file targets that should exist under `changes/<name>/specs/...`.
    Explicitly label which paths are:
    - existing paths reused as-is,
    - existing capability files that need updates,
    - and brand-new domain/context/capability paths to create.
6. For resource-oriented API domains, use operation capabilities under resource ownership:
   - `Domain -> Resource -> Operation Capability`
   - examples include `create/read/list/update/delete` and non-CRUD operations such as `search/archive/reconcile` when behavior requires it.
7. Present options, tradeoffs, and a recommended taxonomy. Pause for user confirmation before locking structure.
8. Produce the final taxonomy tree and spec-path plan.

## Capability framing principles

1. **Product-boundary first**: define boundaries by user/business outcomes and rule ownership.
2. **Implementation-agnostic**: do not use frameworks, storage, transport, or infrastructure as primary taxonomy boundaries.
3. **Capability leaves are spec-ready**: each leaf represents one testable capability outcome.
4. **Centralize invariants**: shared rules have one owning capability; dependent capabilities reference it.
5. **Separate independent outcomes**: if one node contains multiple independently testable outcomes, create separate leaves.
6. **Keep inseparable outcomes together**: if two outcomes cannot be specified or validated independently, keep them in one leaf.
7. **Depth follows boundary clarity**: use as many levels as needed to represent distinct product contexts; stop only when the next level would not add a new product-boundary distinction.

## Output format

Provide:

1. **Existing Taxonomy Snapshot**
   - discovered domain/capability paths
   - quality notes (clear, ambiguous, missing)
2. **Intent Decomposition**
   - actors/workflows/rules/outcomes that drive structure
3. **Proposed Nested Taxonomy**
   - tree: `Domain -> Subdomain/Context -> Capability Leaf`
4. **Taxonomy Artifact Plan**
    - folder tree to create/reuse
    - capability files (final spec filenames)
    - per file/path status: `reuse`, `modify`, or `create`
5. **Ownership Decisions**
    - single-owner decisions for cross-domain rules
6. **Spec File Plan**
   - proposed files under `changes/<name>/specs/...`
   - dependency notes where useful
7. **Open Decisions for User Confirmation**
   - options, recommendation, and consequences

## Quick heuristics

- If a boundary is justified by technology rather than product behavior, reframe it.
- If a rule must be identical across multiple contexts, centralize ownership and reference it.
- If a capability node has multiple independent verbs/outcomes, split it into separate leaves.
- If a requirement spans domains, assign one owning domain/capability and reference from others.
- If a proposed leaf is not testable as written, refine until it is.
- If existing taxonomy cannot cleanly contain intent, introduce new domain/context levels rather than forcing fit.

## Guardrails

- Do not derive boundaries from implementation architecture.
- Do not collapse distinct product contexts into one generic bucket.
- Do not over-split capabilities into implementation-level details.
- Keep taxonomy collaborative: propose, explain, and confirm before finalizing.

## Example shapes

- Product example:
  - `gmail/inbox-organization/search-and-filters/full-text-discovery.md`
- Resource-operation example:
  - `account-management/users/create`
  - `account-management/users/read`
  - `account-management/users/list`
  - `account-management/users/update`
  - `account-management/users/delete`
  - `account-management/users/search`