/component-decision-tree

name: component-decision-tree
description: "Build queryable decision trees that help agents and teams choose between components — structured YAML files mapping user intents to the correct component through a sequence of narrowing questions. This produces selection logic for choosing BETWEEN components, NOT usage guidelines for a single component. Trigger when someone says: component decision tree, which component should I use, help me choose between, selection guide, decision framework, modal vs dialog, intent-to-component mapping, or anything about creating structured logic for picking the right component from alternatives. Do NOT trigger for usage guidance on a specific component — use usage-guidelines for that."
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md

Component decision tree

A skill for building structured decision trees that map user intents and requirements to specific component selections. The output is a queryable framework that AI agents traverse to select the right component for a given need — eliminating the guesswork that leads to component misuse, duplication, and inconsistency.

Context

Component selection is the first decision in any design system interaction, and it is the one that AI agents get wrong most often. The failure mode is not random — it follows predictable patterns. An agent selects a Modal when a Dialog was appropriate. It uses a Card where a List Item fits better. It creates a custom component because it could not find the existing one that serves the need.

These errors have the same root cause: the agent does not have a decision framework. It has a list of components (if it has anything at all) and it pattern-matches the user's request against component names and descriptions. This works when the match is obvious ("I need a button" → Button) and fails when the match requires judgment ("I need to show a collection of items that users can filter and sort" → is that a Table, a DataGrid, a List with filters, or a custom composition?).

Decision trees encode the judgment. Instead of relying on an agent's ability to infer the right component from a description, the tree asks a structured sequence of questions that narrow the selection to the correct component. The questions are the same ones a senior designer or developer would ask when advising a junior team member.

The practical output is a structured file that agents load alongside component metadata. When an agent receives a request, it traverses the decision tree first to identify the component, then loads the component's metadata for configuration details.

Boundaries

This skill produces decision trees for component selection — choosing between components. It does not document how to use a single component once selected (use `usage-guidelines` for that) or generate component metadata schemas (use `metadata-schema-generator`). If the system has fewer than 5 components, a decision tree adds overhead without value — a simple component index is sufficient. If no component inventory exists, run `component-audit` or `codebase-index` first to establish one.

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `system.component_paths` — directs scanning to component directories
• `system.category_model` — determines top-level decision tree branches (atomic, functional, custom)
• `integrations.*` — enables auto-pull for component data
• `decision_tree.output_format` — output format preference (JSON or YAML, default: YAML)

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically:

**Figma MCP** (`integrations.figma.enabled: true`):

• Read the published component library from `integrations.figma.file_key`
• Extract component names, descriptions, and variant structures
• Use descriptions as input for decision node generation

**Storybook** (`integrations.storybook.enabled: true`):

• Fetch the story index for a complete component list
• Extract documented use cases from story titles and descriptions

**Codebase index** (`.ai/index/component-inventory.yml`):

• If a codebase index exists, load the component inventory and relationship graph
• Use category assignments and relationship data to inform tree structure

If an integration fails, log it and proceed with available sources.

---

Step 1: Map the component landscape

Before building decision trees, understand what components exist and how they cluster.

**Component inventory**: List every component with its purpose and category. If a codebase index exists, use it. If not, scan the component directories.

**Functional clusters**: Group components by the user need they serve, not by their technical category. A single user need often spans multiple components:

| User need | Components that serve it | |---|---| | Show a notification | Toast, Banner, Alert, InlineMessage, Snackbar | | Collect user input | Input, TextArea, Select, Combobox, DatePicker, Checkbox, Radio, Switch | | Navigate between views | Tabs, Sidebar, Breadcrumb, Pagination, BottomNav | | Display a collection | Table, DataGrid, List, CardGrid, Timeline | | Confirm an action | Dialog, ConfirmationModal, AlertDialog | | Show contextual info | Tooltip, Popover, HoverCard, Dropdown |

**Overlap analysis**: Identify components with overlapping use cases. These are the decision points where agents (and humans) get confused:

| Component A | Component B | Distinguishing factor | |---|---|---| | Modal | Dialog | Modal blocks the page; Dialog is for focused tasks with a specific outcome | | Toast | Banner | Toast is transient and non-blocking; Banner persists until dismissed | | Select | Combobox | Select has a fixed option list; Combobox allows search/filter |

Ask for or confirm:

• Are there components that teams frequently confuse or misuse? (These are high-priority decision points)
• Are the