---
name: refine-feature
description: Decomposes a planned screen into implementable features and details components, data, and validation criteria. Use between /plan-project and /build-feature.
metadata:
  category: Feature Definition
---

# Skill: Refine Feature

Takes a screen from the project plan, decomposes it into implementable features, and adds the detail work (components, data structures, validation criteria) that `/plan-project` intentionally left out. Each feature becomes a single `/build-feature` invocation.

## When to use

- After `/plan-project` is approved and before the first `/build-feature`
- For each screen before implementing it
- When a screen looks complex and you're unsure if it should be one or multiple `/build-feature` passes

## Prerequisites

### Pre-flight (BLOCKING)

Complete the pre-flight check in `sandbox-preflight.md`. You must have read both COMPONENTS.md files, `newTokens.ts`, and the `types.ts` of each component you plan to use.

⛔ Do NOT proceed until the pre-flight is complete. The scaffold must exist (`node_modules/` present) — if it doesn't, stop and run `/bootstrap-react-project` first.

Before mapping components or proposing pseudo-snippets, also read these shared files:
- **`references/CONVENTIONS.md`** — team conventions for component choices and styling (MUST follow)
- **`references/PATTERNS.md`** — code snippets for common UI patterns (use as base for implementation)

## Steps

### 1. Read screen context (delegate to haiku)

Launch a subagent to query the features database and get context for this screen:

```
Agent({
  model: "haiku",
  prompt: `
    Fetch this Notion page: {notionPageUrl}
    Read the Features database embedded in the page.

    Return all records where Screen = "{screenName}" and Módulo = "{moduleName}".
    For each record return: Name, Estado, Descripción, Orden, Criterios.

    Also return a summary of all other records grouped by Módulo → Screen with their Estado,
    so we have context on overall project progress.
  `
})
```

### 2. Analyze the screen for splitting (run directly — Sonnet)

Look at the design screenshots and ask these questions:

**Does it have distinct visual states?**
- Empty state vs populated state → separate features
- Loading state vs loaded → usually same feature
- Error state → separate only if it has its own layout

**Does it have components that open/close?**
- Drawer → separate feature
- Dialog/Modal → separate feature
- Menu → usually part of the parent feature (menus are small)

**Does it have complex interactions?**
- Drag-and-drop reordering → separate feature
- Inline editing → separate feature
- Filters that change the view → separate feature

**Can each piece be visually validated on its own?**
- If the user can open the browser and say "sí, esto se ve bien" for a piece in isolation → it's a good feature
- If a piece only makes sense together with another → keep them together

### 3. Propose the decomposition to the user (run directly — Sonnet)

Present the features in implementation order:

> La pantalla "[nombre]" tiene [N] partes que conviene construir por separado:
>
> 1. **[Sub-feature name]** — [qué incluye]. Se valida: [qué debería ver el usuario].
> 2. **[Sub-feature name]** — [qué incluye]. Se valida: [qué debería ver el usuario].
> 3. **[Sub-feature name]** — [qué incluye]. Se valida: [qué debería ver el usuario].
>
> ¿Te parece este orden, o preferís cambiar algo?

**Rules for good decomposition:**
- Each feature should be completable in a single `/build-feature` pass
- Each feature should be visually validatable by the user
- The order should be dependency-driven: build the base first, then things that depend on it
- Shared layout/structure (header, stepper, footer) is the first feature if not already built

Wait for user confirmation. They may merge, split further, or reorder.

### 4. Lookup components (delegate to haiku)

Launch a subagent to find the right patterns from references/PATTERNS.md:

```
Agent({
  model: "haiku",
  prompt: `
    Read the file: {pluginPath}/references/PATTERNS.md

    For each of these UI patterns, find and return the matching snippet:
    {list of patterns needed, e.g.: "page layout with title header", "empty state", "table with pagination"}

    Return each snippet with its section name.
  `
})
```

### 5. Map components per feature (run directly — Sonnet)

Component lookup order (stop at the first level that covers the pattern):

1. **`references/PATTERNS.md`** — pre-curated snippets for the most common patterns. If the component and props are there, use them directly.
2. **`COMPONENTS.md` de design-system** — base DS components. Use when composed-components don't cover the case.
3. **`COMPONENTS.md` de composed-components** — higher-level composed components that combine multiple DS primitives. Check the Preferred Patterns section at the end.
4. **`types.ts` del componente** — read only if the above don't clarify the exact props needed.

Using the patterns found and the conventions from `references/CONVENTIONS.md`, build the initial component list for each feature. Then delegate the Storybook URL lookup to haiku:

```
Agent({
  model: "haiku",
  prompt: `
    For each component in this list: {componentList}

    1. Derive the stories file path from the import path:
       @material-hu/components/{path} → src/components/{path}/{ComponentName}.stories.tsx
       Read it from the material-hu repo.

    2. Extract:
       - The "title" field (e.g. "Design System/Buttons/Button")
       - The name of the first exported story (e.g. "Default", "Primary")

    3. Build the Storybook URL:
       - Convert title to kebab-case: "Design System/Buttons/Button" → "design-system-buttons-button"
       - Story name to kebab-case: "Default" → "default"
       - URL: https://hugo.humand.co/?path=/story/{title-kebab}--{story-name-kebab}

    Return for each component: { name, storyUrl }
  `
})
```

With the URLs from haiku, build the component table for each feature:

| Sección | Componente | Storybook | Import path | Prop clave | Valor / Fuente |
|---|---|---|---|---|---|

Rules:
- **Import path** must be the exact `@material-hu/components/...` path. Never use raw MUI imports.
- **Apply team conventions** — check `references/CONVENTIONS.md` before proposing any component.
- **Use Form variants** for any component inside a form.
- **Prefer composed-components** over manual combinations of DS primitives.

### 6. Propose with pseudo-snippets (run directly — Sonnet)

For each feature section, show a pseudo-snippet so the user can validate the exact component + props BEFORE implementation:

```
// Header de página
<Title title="Onboarding" description="..." variant="L" />
<Button variant="primary" size="large" startIcon={<IconPlus />}>
  Nuevo proceso
</Button>

// Empty state
<StateCard slotProps={{
  title: { title: '...', description: '...', variant: 'M' },
  avatar: { Icon: IconInfoCircle, color: 'default' },
}} />
```

This catches prop/component mismatches before any code is written.

### 7. Validate data structure (run directly — Sonnet)

For every feature that has data (tables, lists, sample values in the design), ask the user:

- **¿Cuáles son todos los campos que devuelve este endpoint?**
- **¿Hay campos ocultos que se necesiten?** (e.g. `id` for row click)
- **¿Cuál es la URL real del endpoint?** (to populate `mock/db.json`)

Add a data structure table:

| Campo | Tipo | Visible en UI | Fuente |
|---|---|---|---|

Column notation:
- **Tipo** — TypeScript type: `string`, `number`, `boolean`, `Date`, or a union like `"active" \| "inactive"`
- **Visible en UI** — `Sí` or `No`
- **Fuente** — `/endpoint-path → fieldName` for API fields, or `input del usuario` for form inputs

### 8. Propose validation criteria per feature (run directly — Sonnet)

For each feature, propose 2-4 validation criteria in plain Spanish:

- ✅ "Al entrar a la pantalla se ve el empty state con el botón de nuevo paso"
- ✅ "Puedo expandir y colapsar un paso con el chevron"
- ❌ "El componente StepCard renderiza correctamente" ← too technical

### 9. Create feature records in the database (delegate to haiku)

```
Agent({
  model: "haiku",
  prompt: `
    In the Features database on Notion page {notionPageUrl}, create one record per feature:

    {for each feature:}
    - Name: "{featureName}"
    - Módulo: "{moduleName}"
    - Screen: "{screenName}"
    - Estado: "Pendiente"
    - Descripción: "{one-line description}"
    - Orden: {number}
    - Criterios: "{validation criteria, one per line}"

    For each record, also write its internal page with:
    ## Componentes
    {component table: | Sección | Componente | Storybook | Import path | Prop clave | Valor / Fuente |}

    ## Estructura de datos
    {data structure table if applicable: | Campo | Tipo | Visible en UI | Fuente |}

    ## Pseudo-snippet
    {validated pseudo-snippet}
  `
})
```

### 10. Hand off to /build-feature

Once the user approves:
> Listo, actualicé el plan. Arrancamos con la primera feature: "[feature name]".

Then invoke `/build-feature` for the first feature.
