Comandos de planificación: craft, shape, document, extract

En el capítulo anterior vimos cómo el detector aplica 44 reglas deterministas para señalar problemas concretos en código ya escrito. Esa es la mitad reactiva de Impeccable: te dice qué está mal cuando algo ya existe. Pero el verdadero salto de calidad ocurre antes, cuando todavía no has escrito una sola línea. Como recoge la propia documentación del comando shape, “la mayoría de las interfaces generadas por IA fallan no por mal código, sino por pensamiento omitido”. Este capítulo cubre los cuatro comandos de planificación que existen precisamente para no omitir ese pensamiento: craft, shape, document y extract.

Todos comparten el mismo patrón de invocación que ya conoces desde el capítulo de contexto de diseño: se llaman a través del skill de Impeccable con la forma /impeccable <comando> <target>. El <target> es opcional según el comando y describe sobre qué quieres operar. Por ejemplo:

/impeccable craft landing
/impeccable shape "panel de ajustes de cuenta"
/impeccable document
/impeccable extract

La idea de fondo es sencilla pero poderosa: en lugar de pedirle al agente “hazme una landing” y rezar para que el resultado tenga criterio, le das un comando que estructura el razonamiento de diseño antes, durante o después de implementar. Veamos cada uno.

El patrón general: /impeccable <comando> <target>

Antes de entrar en cada comando conviene fijar el modelo mental. Impeccable es una design skill para agentes de coding: no es una CLI que renderice pantallas, sino un conjunto de instrucciones y archivos de referencia que el agente carga y sigue. Cuando escribes /impeccable craft landing, el agente lee el flujo descrito en su archivo de referencia craft.md y lo ejecuta paso a paso, cargando otros archivos de referencia (layout.md, typeset.md, colorize.md, etc.) según lo que necesite.

Los cuatro comandos de este capítulo se reparten así:

• craft y shape miran hacia adelante: planifican y construyen algo nuevo.
• document y extract miran hacia el código existente: lo capturan y lo consolidan en un sistema reutilizable.

flowchart LR
    A[Idea o feature] --> B["/impeccable shape"]
    B -->|brief aprobado| C["/impeccable craft"]
    C --> D[Feature implementada]
    D --> E["/impeccable extract"]
    E --> F[Componentes y tokens reutilizables]
    D --> G["/impeccable document"]
    G --> H[DESIGN.md actualizado]
    F --> H

Fíjate en la dirección: shape alimenta a craft, y lo que craft produce se puede consolidar después con extract y registrar con document. No es obligatorio usar los cuatro siempre, pero entender cómo encadenan es lo que te convierte de usuario a “hero”.

craft: construir una feature con calidad de producción

El comando craft es el flujo más completo de los cuatro. Su propósito, según su referencia, es “construir features con calidad de UX y UI impecable”, combinando validación de diseño, dirección visual, implementación de código de nivel producción e inspección iterativa. Es decir: no genera solo una maqueta ni solo código suelto, sino que orquesta todo el proceso de extremo a extremo.

Cuándo usarlo

Usa craft cuando:

• Construyes una feature de cara al usuario que exige rigor de diseño.
• El proyecto requiere que tanto la dirección visual como la calidad del código importen por igual.
• Necesitas alineación con stakeholders antes de implementar.

Qué produce

El resultado de craft es una feature completamente implementada y validada visualmente que:

• Se ajusta a una dirección de diseño aprobada.
• Cumple estándares de calidad de producción.
• Pasa pruebas de responsive y de estados.
• Se entrega con contenido real y estructura semántica.

Entradas típicas

Como target recibe la descripción de la feature del usuario, y además se apoya en:

• PRODUCT.md (el contexto de producto que creaste con init).
• El framework o sistema de diseño existente, si lo hay.
• Un brief de diseño confirmado, que puede venir de /impeccable shape o aportarlo tú directamente.

El flujo de craft en 6 pasos

Lo que distingue a craft de un simple “hazme esto” es que internamente sigue un proceso de seis pasos con gates (puertas de control) que no se pueden saltar:

sequenceDiagram
    participant U as Usuario
    participant C as craft
    participant S as shape
    U->>C: /impeccable craft landing
    C->>C: Paso 0 - Detectar framework, librería, iconos
    C->>S: Paso 1 - Confirmar dirección de diseño
    S-->>U: Brief de diseño
    U-->>C: Aprobación explícita
    C->>C: Paso 2 - Cargar referencias (layout, typeset...)
    C->>C: Paso 3 - Generar mocks visuales (si hay imagen)
    C->>C: Paso 4 - Implementar a nivel producción
    C->>C: Paso 5 - Inspeccionar en navegador y parchear
    C-->>U: Paso 6 - Presentar con crítica honesta

1. Paso 0 — Detectar la base del proyecto: framework, librería de componentes, set de iconos.
2. Paso 1 — Ejecutar /impeccable shape para confirmar la dirección de diseño; pausar para que el usuario apruebe.
3. Paso 2 — Cargar los archivos de referencia relevantes (layout.md, typeset.md, etc.) según las necesidades.
4. Paso 3 — Generar maquetas visuales (si el entorno soporta generación de imágenes); si no, se omite.
5. Paso 4 — Implementar al nivel de producción: semántico, espaciado, interactivo, completo en estados y accesible.
6. Paso 5 — Inspeccionar en el navegador (responsive, estados, detalles de craft); parchear defectos y volver a inspeccionar.
7. Paso 6 — Presentar resultados con crítica honesta y limitaciones pendientes.

La regla crítica: los gates no se comprimen

Hay una regla que merece su propia sección porque es el corazón de la filosofía de Impeccable: “la confirmación del shape por sí sola NO es luz verde para empezar a codear”.

El comportamiento cambia según el entorno:

• Con generación de imágenes: el flujo es shape → preguntas de dirección → paleta → aprobación del mock → código. Son varios gates encadenados.
• Sin generación de imágenes: los gates se colapsan y la confirmación del shape avanza directamente al código.

Esto evita el problema clásico de los agentes: saltar de “entendido” a “ya lo implementé todo” en la misma respuesta, sin que tú hayas validado nada.

Checklist de entregable

Una feature craft solo se considera terminada si cumple:

• Contenido real (sin placeholders tipo “Lorem ipsum”).
• Los ingredientes principales del mock aprobado, preservados.
• HTML semántico y accesibilidad.
• Espaciado y tipografía deliberados.
• Cobertura de estados (hover, focus, loading, error, etc.).
• Interacción por teclado y por toque.
• Imágenes optimizadas.
• Respeto al pipeline de build del proyecto.
• Cero errores en consola.

Ejemplo realista

/impeccable craft "página de precios con 3 planes y un toggle mensual/anual"

A partir de ahí el agente detectará tu stack, te confirmará un brief de diseño, esperará tu aprobación, implementará la página de precios con sus estados, la inspeccionará en navegador y te la presentará señalando honestamente qué quedó fuera.

shape: dar forma a la UX y UI antes de escribir código

Si craft es el flujo completo, shape es su primera pieza, y puede usarse de forma independiente. Su propósito es producir un design brief (resumen de diseño) antes de que empiece la implementación. Está pensado para equipos que quieren validar la dirección de UX/UI mediante un descubrimiento estructurado en lugar de saltar al código.

El problema que resuelve

La documentación de shape lo expresa sin rodeos: la mayoría de las UIs generadas por IA fallan por “pensamiento omitido”. shape invierte el flujo típico: en vez de adivinar, entiende a fondo las necesidades del usuario antes de tomar decisiones de diseño, para que la implementación sea precisa y no producto de la suposición.

Qué produce

Un design brief, un artefacto estructurado que contiene:

• Resumen de la feature y acción principal del usuario.
• Dirección visual (estrategia de color, “frase de escena”, anclas de referencia).
• Definición de alcance (fidelidad, amplitud, interactividad, intención de tiempo).
• Estrategia de layout y estados clave.
• Modelo de interacción y requisitos de contenido.
• Archivos de referencia recomendados para la implementación.

El flujo de shape

shape opera en fases:

• Fase 1 — Entrevista de descubrimiento (obligatoria): un diálogo natural que cubre propósito, audiencia y métricas de éxito; alcance de contenido y rangos de datos realistas; dirección visual; parámetros de alcance y restricciones; anti-objetivos y evaluación de riesgos. La cadencia es de 2 a 3 preguntas por ronda, con un mínimo de una ronda. Si PRODUCT.md o DESIGN.md ya responden algo, esas preguntas se omiten.
• Fase 1.5 — Sondeos de dirección visual (condicional): cuando se dan las condiciones (trabajo totalmente nuevo, fidelidad media o superior, generación de imágenes nativa disponible), se generan de 2 a 4 sondeos visuales distintos para probar la dirección antes de cerrar el brief.
• Fase 2 — Design brief (con gate de confirmación): presenta el brief terminado en forma compacta (3 a 5 viñetas) o estructurada completa, y luego pausa esperando confirmación explícita.

Reglas clave

• No se escribe código durante el descubrimiento ni la creación del brief.
• La confirmación es obligatoria: “la pausa es lo que separa shape de la implementación prematura”. La regla es explícita: “no presentes un brief y luego sigas codeando en la misma respuesta”.
• Afirmar en lugar de ofrecer menús: cuando la respuesta es clara, el comando recomienda una dirección con un “¿confirmas o cambias?” en vez de listar opciones interminables.
• Los sondeos visuales son opcionales, no un reemplazo del descubrimiento, y se omiten si no hay generación de imágenes nativa.
• Los parámetros de alcance son de la tarea: no persisten más allá del brief.

Ejemplo realista

/impeccable shape "dashboard de analítica para un equipo de marketing"

El agente te hará un par de rondas de preguntas (¿quién lo usa?, ¿qué métrica define el éxito?, ¿qué referencias visuales te gustan?, ¿qué NO debe parecer?), te propondrá una dirección, y se detendrá hasta que confirmes. Solo entonces, si lo encadenas con craft, empezará a implementar.

document: generar la documentación del sistema de diseño

El comando document genera un archivo DESIGN.md en la raíz del proyecto que captura el sistema de diseño visual en dos capas: una legible por máquina (frontmatter YAML) y otra legible por humanos (markdown). El objetivo es que los agentes de IA se mantengan “on-brand” al generar nuevas pantallas. Este es el mismo DESIGN.md que conociste en el capítulo 3, pero ahora veremos el comando que lo produce y mantiene.

Cuándo usarlo

• Después de /impeccable init, para documentar el sistema visual.
• Cuando aún no existe ningún DESIGN.md.
• Cuando un sistema de diseño existente ha derivado y necesita refrescarse.
• Antes de un rediseño grande, para capturar el estado actual como referencia.

Dos modos de operación

document tiene dos modos según en qué punto esté tu proyecto:

Modo Scan (por defecto) — Extrae el sistema automáticamente del código existente y de la salida renderizada. El comando hace grep del código en orden de prioridad: custom properties CSS (--color-, --font-, --spacing-, --radius-, --shadow-, --ease-, --duration-), config de Tailwind, archivos de theme en CSS-in-JS (theme.ts, tokens.ts), archivos de tokens (tokens.json), la librería de componentes y la hoja de estilos global. Después agrupa colores en roles Primary/Secondary/Tertiary/Neutral, mapea la tipografía a una jerarquía Display/Headline/Title/Body/Label, cataloga el vocabulario de sombras y, mediante una sola interacción AskUserQuestion, te pide la capa cualitativa (la “Creative North Star”, el tono de voz, los nombres descriptivos de colores, la filosofía de elevación y de componentes).

Modo Seed — Para proyectos pre-implementación donde todavía no hay sistema visual que extraer. Se dispara con /impeccable document --seed, o se ofrece automáticamente si el scan no encuentra tokens ni componentes ni salida renderizada. En este modo, en vez de escanear, hace cinco preguntas de entrevista (estrategia de color, dirección tipográfica, energía de movimiento, tres referencias con nombre y una anti-referencia) y escribe un DESIGN.md semilla con placeholders honestos, encabezado por un comentario que recuerda volver a ejecutar el comando cuando ya haya código.

flowchart TD
    A["/impeccable document"] --> B{¿Hay código y tokens?}
    B -->|Sí| C[Modo Scan]
    B -->|No| D[Modo Seed]
    C --> E[Grep de tokens y componentes]
    E --> F[AskUserQuestion: capa cualitativa]
    F --> G["DESIGN.md + .impeccable/design.json"]
    D --> H[5 preguntas de entrevista]
    H --> I["DESIGN.md semilla con placeholders"]

Qué produce

El modo scan genera dos archivos:

• DESIGN.md en la raíz: frontmatter YAML normativo (con colors, typography, rounded, spacing, components) más seis secciones markdown en orden fijo y con encabezados exactos: Overview, Colors, Typography, Elevation, Components y Do’s and Don’ts.
• .impeccable/design.json (sidecar, solo en modo scan): un archivo de esquema versión 2 que guarda lo que el esquema de 8 propiedades no puede contener: metadatos de color (rampas tonales, OKLCH canónico), metadatos de tipografía, sombras, movimiento, breakpoints, y snippets HTML/CSS autocontenidos de 5 a 10 componentes canónicos.

Reglas importantes

• El frontmatter es normativo: los valores definidos ahí son la fuente de verdad. La prosa contextualiza, nunca redefine.
• No sobrescribe sin confirmación: si DESIGN.md ya existe, el comando te muestra el archivo y usa AskUserQuestion para aclarar si refrescar, sobrescribir o fusionar.
• Encabezados de sección con coincidencia exacta: es “Colors”, no “Color Palette & Roles”; el parsing de las herramientas depende de los nombres exactos.
• Citar anti-referencias de PRODUCT.md por su nombre: si PRODUCT.md lista “glassmorphism” como algo a evitar, la sección Don’ts debe repetir esa palabra literalmente.

Ejemplos de invocación

# Modo scan por defecto (auto-extrae y luego pide la capa cualitativa)
/impeccable document

# Forzar modo seed para proyectos pre-implementación
/impeccable document --seed

# Tras cambios, refrescar un DESIGN.md existente
# (el comando pide confirmar: sobrescribir o fusionar)
/impeccable document

extract: consolidar patrones en un sistema reutilizable

El comando extract sistematiza el descubrimiento y la consolidación de patrones de diseño, componentes y tokens repetidos en un sistema de diseño centralizado. Mientras document captura y describe lo que ya existe, extract refactoriza y unifica: toma las tres tarjetas casi idénticas que copiaste y pegaste por todo el código y las convierte en un único componente con una API limpia.

Cuándo usarlo

Aplica extract cuando hayas identificado patrones de UI repetidos que aparecen 3 o más veces con la misma intención, o cuando valores de diseño hard-codeados deberían convertirse en tokens estandarizados. Esa regla de “3 o más veces con la misma intención” es la guía central: evita que extraigas abstracciones prematuras a partir de un solo uso.

El flujo de extract

1. Localizar el sistema de diseño y entender su arquitectura, convenciones de nombres y estructura. Regla crítica: “si no existe sistema de diseño, PARA y llama a la herramienta AskUserQuestion” antes de continuar.
2. Escanear oportunidades de extracción: componentes repetidos, valores hard-codeados, variaciones inconsistentes, patrones de composición, estilos de tipografía y patrones de animación. La guía insiste: “solo extrae cosas usadas 3 o más veces con la misma intención”.
3. Crear un plan de extracción sistemático que documente componentes objetivo, tokens, variantes, alineación de nombres y estrategia de refactor.
4. Construir versiones mejoradas y reutilizables con APIs claras, variantes adecuadas, soporte de accesibilidad y documentación.
5. Reemplazar las implementaciones existentes con las versiones compartidas mediante búsqueda y reemplazo sistemáticos, y pruebas exhaustivas.
6. Actualizar la documentación del sistema de diseño con los nuevos componentes, el uso de tokens y las guías.

Restricciones críticas

• No extraigas implementaciones de un solo uso.
• No crees componentes demasiado genéricos.
• No conviertas en tokens valores sin significado semántico.
• No te saltes los tipos de TypeScript ni la documentación.

Ejemplo realista

/impeccable extract

El agente buscará tu sistema de diseño, escaneará el código en busca de patrones repetidos (por ejemplo, el botón con padding: 16px 48px que aparece en siete sitios), te propondrá un plan, construirá los componentes y tokens compartidos, y sustituirá los usos uno a uno. Si no encuentra un sistema de diseño donde colocarlos, se detendrá y te preguntará antes de inventarse una estructura.

Tabla comparativa de los cuatro comandos

Comando	Dirección	Propósito	Target / entrada típica	Salida esperada
craft	Hacia adelante	Construir una feature completa con calidad de producción	Descripción de la feature + PRODUCT.md + brief confirmado	Feature implementada, validada en navegador y con crítica honesta
shape	Hacia adelante	Dar forma a la UX/UI mediante descubrimiento antes de codear	Descripción de la feature o idea	Design brief estructurado, con gate de confirmación
document	Hacia el código	Documentar el sistema de diseño visual	El código existente (scan) o respuestas de entrevista (seed)	DESIGN.md + .impeccable/design.json (en scan)
extract	Hacia el código	Consolidar patrones repetidos en componentes y tokens reutilizables	Patrones usados 3+ veces + sistema de diseño existente	Componentes y tokens compartidos + docs actualizadas

Cómo encajan en el flujo

Recuperando el contexto del capítulo 3, donde init sembró PRODUCT.md y DESIGN.md, estos cuatro comandos son la fase de planificación y construcción que se apoya en ese contexto. El ciclo natural de trabajo es:

flowchart LR
    subgraph Contexto["Cap. 3 — Contexto"]
        I[init]
    end
    subgraph Planificacion["Cap. 5 — Planificación"]
        S[shape]
        C[craft]
        D[document]
        E[extract]
    end
    subgraph Revision["Cap. 6 y 7 — Revisión y refinamiento"]
        R[critique / audit / polish]
    end
    I --> S --> C --> R
    C --> E --> D
    I -.contexto.-> C
    I -.contexto.-> D

Primero das forma con shape, luego construyes con craft apoyado en PRODUCT.md y DESIGN.md. Una vez tienes varias features, extract consolida lo repetido en componentes reutilizables y document mantiene DESIGN.md al día reflejando el sistema real. Y cuando todo está en su sitio, pasas a la fase de revisión y refinamiento con critique, audit y polish, que veremos en el capítulo 6.

Resumen

Los cuatro comandos de planificación de Impeccable se reparten en dos ejes. Mirando hacia adelante, shape produce un design brief mediante descubrimiento estructurado (con un gate de confirmación innegociable que separa el pensar del codear) y craft orquesta el flujo completo de seis pasos hasta una feature de calidad de producción, validada en navegador y entregada con crítica honesta. Mirando hacia el código existente, document captura el sistema de diseño en DESIGN.md y su sidecar .impeccable/design.json (en modo scan o seed) y extract consolida patrones repetidos 3 o más veces en componentes y tokens reutilizables. Todos se invocan con el patrón /impeccable <comando> <target> y se apoyan en el contexto que sembraste con init. La lección de fondo es la misma que motiva todo Impeccable: el diseño impecable no nace de mejor código, sino de no saltarse el pensamiento previo.

Siguiente: Comandos de revisión: critique, audit, polish