Comandos de revisión: critique, audit, polish

En el capítulo anterior aprendiste a usar los comandos de planificación (craft, shape, document, extract) para definir qué construir antes de escribir una sola línea. Pero planificar y construir no basta: el verdadero salto de calidad ocurre cuando alguien (o algo) mira tu interfaz con ojos críticos y te dice, sin rodeos, qué está mal y por qué. Esa es la función de los tres comandos de revisión de Impeccable.

En este capítulo vamos a desmenuzar critique, audit y polish. Los tres revisan tu trabajo, pero cada uno opera en un nivel distinto: critique te da una opinión de diseño honesta y una dirección, audit ejecuta una verificación técnica sistemática contra una checklist medible, y polish ya no opina sino que ejecuta las mejoras finas. Entender la diferencia entre los tres es lo que separa a quien usa Impeccable como un linter de quien lo usa como un director de arte.

Por qué tres comandos y no uno

Podrías preguntarte por qué Impeccable separa la revisión en tres comandos en lugar de tener un único “revisa esto”. La respuesta es que revisar diseño tiene tres modos cognitivos muy distintos, y mezclarlos produce feedback confuso.

• Opinión y dirección (critique): “Esto se siente genérico, falta personalidad, y la jerarquía visual no guía la mirada”. Es subjetivo, holístico, y su valor está en señalar el rumbo.
• Verificación sistemática (audit): “El contraste del botón secundario es 3.1:1, por debajo del mínimo WCAG AA de 4.5:1”. Es objetivo, medible, y su valor está en la exhaustividad.
• Ejecución del pulido (polish): no te dice nada, arregla el espaciado inconsistente, el estado de hover que falta y el microcopy mal capitalizado. Su valor está en cerrar la brecha entre “funciona” y “está impecable”.

flowchart LR
    A[Interfaz construida] --> B[critique]
    A --> C[audit]
    B -->|opinión y dirección| D[Decides qué arreglar]
    C -->|checklist técnica| D
    D --> E[polish]
    E -->|ejecuta mejoras finas| F[Interfaz impecable]
    style B fill:#dbeafe
    style C fill:#dcfce7
    style E fill:#fef3c7

Los tres se invocan con la misma forma que el resto de comandos de Impeccable: /impeccable <comando> <target>, donde el target puede ser una descripción (“la homepage”, “blog”), una ruta de archivo o una URL.

critique: la crítica de diseño honesta

El comando critique es el más ambicioso de los tres. No se limita a buscar errores: emite un juicio de diseño completo, combinando una revisión de diseño (subjetiva, basada en heurísticas y experiencia) con un escaneo del detector (determinista, las 44 reglas que viste en el capítulo 4). Luego sintetiza ambas evaluaciones en un informe priorizado.

Cómo funciona por dentro

Cuando ejecutas critique, el flujo es el siguiente:

1. Resuelve el target: convierte tu entrada (“la homepage”) en una ruta concreta (site/pages/index.astro). Prefiere rutas de código fuente antes que URLs del servidor de desarrollo.
2. Calcula un slug: genera un identificador estable para poder persistir el resultado y rastrear la evolución en el tiempo.
3. Lee la lista de ignorados: si existe .impeccable/critique/ignore.md, descarta silenciosamente los hallazgos que coincidan. Es la única entrada de ejecuciones previas.
4. Ejecuta dos evaluaciones independientes (A y B) y las sintetiza.

Evaluación A: revisión de diseño

Esta es la parte “humana” del juicio. Evalúa archivos fuente y páginas en vivo cubriendo:

• Detección de “AI slop”: composición genérica, falta de personalidad, layouts que se parecen a todo lo demás.
• Diseño holístico: jerarquía, arquitectura de la información, encaje emocional, tipografía, color, accesibilidad, estados, copy y casos límite.
• Carga cognitiva: aplica una checklist de 8 ítems sobre violaciones de la memoria de trabajo.
• Recorrido emocional: aplica la regla peak-end, busca valles y momentos de reaseguro.
• Heurísticas de Nielsen: puntúa las 10 heurísticas de 0 a 4.

Evaluación B: detector + evidencia del navegador

Esta es la parte determinista. Ejecuta el detector por CLI sobre los archivos de markup:

node .claude/skills/impeccable/scripts/detect.mjs --json [target]

El código de salida 0 significa limpio y 2 significa que encontró hallazgos. Para URLs, en lugar del CLI usa una visualización en el navegador: levanta un servidor en vivo, inyecta un script de detección (detect.js) y lee la consola en busca de mensajes impeccable. Esta visualización es la base del comando live, que veremos en el capítulo 11.

Qué devuelve critique

El informe combinado tiene una estructura fija y muy rica. Estas son sus piezas principales:

• Tabla de Design Health Score: las 10 heurísticas de Nielsen puntuadas de 0 a 4, con un total sobre 40 y una banda de calificación.
• Veredicto de anti-patrones: ¿parece generado por IA? ¿qué encontró el detector? ¿se ven los overlays en el navegador?
• Impresión general: reacción honesta de qué funciona y cuál es la mayor oportunidad.
• Qué funciona: 2 o 3 fortalezas concretas con razones específicas.
• Priority Issues: de 3 a 5 problemas, cada uno etiquetado con su severidad (P0 a P3), con el qué, el por qué importa, el fix y un comando sugerido.
• Persona Red Flags: recorre la acción principal con 2 o 3 personas (Alex el power user, Jordan el primerizo, Sam dependiente de accesibilidad, Riley el que estresa el sistema, Casey en móvil y distraído) y lista qué elementos les fallan.
• Observaciones menores y preguntas provocadoras que abren mejores soluciones.

La banda de calificación del Design Health Score funciona así:

Rango (sobre 40)	Banda
36 - 40	Excellent
28 - 35	Good
20 - 27	Acceptable
12 - 19	Poor
0 - 11	Critical

Y las severidades de cada hallazgo son consistentes en los tres comandos:

Tag	Nombre	Significado
P0	Blocking	Imposible completar la tarea; arréglalo ya
P1	Major	Dificultad significativa; arréglalo antes de publicar
P2	Minor	Existe un workaround; arréglalo en la siguiente pasada
P3	Polish	Sin impacto real; arréglalo si hay tiempo

El almacenamiento de critiques

Aquí entra una pieza que distingue a critique de los demás: la persistencia. Tras finalizar el informe, Impeccable lo guarda en .impeccable/critique/ usando el script critique-storage.mjs:

IMPECCABLE_CRITIQUE_META='{"target":"blog","total_score":32,"p0_count":0,"p1_count":2}' \
  node .claude/skills/impeccable/scripts/critique-storage.mjs write <slug> <body-file>

Y para leer la tendencia de las últimas ejecuciones:

node .claude/skills/impeccable/scripts/critique-storage.mjs trend <slug> 5

Esto permite que, al final de cada crítica, veas una línea como Trend for blog (last 5 runs): 24 → 28 → 32 → 29 → 32. La idea es poderosa: el diseño deja de ser una evaluación puntual y se convierte en una métrica que evoluciona. Puedes ver si tus cambios mejoran o empeoran la salud de diseño con cada iteración. Un fallo en el almacenamiento nunca bloquea la crítica.

Ejemplo de invocación

/impeccable critique blog

Impeccable resolverá “blog” a la ruta correspondiente, ejecutará ambas evaluaciones y te devolverá la tabla de salud, los priority issues y, al final, te hará entre 2 y 4 preguntas concretas (vía AskUserQuestion) basadas en los hallazgos reales: por ejemplo, “Encontré problemas de jerarquía visual, color y sobrecarga de información. ¿Cuál te importa más?”. Según tu respuesta, te listará comandos en orden de prioridad, cerrando siempre con /impeccable polish como paso final.

audit: la auditoría técnica sistemática

Mientras critique opina, audit verifica. Es una revisión de calidad técnica a nivel de código, enfocada en problemas medibles de implementación en lugar de en la crítica de diseño. Combina detección automática con el juicio del agente para evitar falsos positivos, pero su columna vertebral es una checklist objetiva.

Las cinco dimensiones

audit puntúa cinco dimensiones, cada una de 0 a 4:

1. Accessibility (A11y): ratios de contraste, etiquetas ARIA, navegación por teclado, HTML semántico, texto alternativo y formularios.
2. Performance: layout thrashing, animaciones costosas, lazy loading, tamaño del bundle y optimización del render.
3. Responsive Design: anchos fijos, áreas táctiles (mínimo 44x44 px), overflow, escalado de texto y cobertura de breakpoints.
4. Theming: design tokens, variantes de dark mode, consistencia de color y comportamiento del cambio de tema.
5. Anti-Patterns (CRÍTICO): “tells” de diseño generado por IA (glassmorphism, gradient text, fuentes genéricas) y anti-patrones de UX generales.

Qué reporta

El informe de audit incluye:

• Audit Health Score table: cada dimensión mapeada a su puntuación con los hallazgos clave.
• Total sobre 20 con su banda de calificación.
• Veredicto de anti-patrones: identifica las características de “AI slop”.
• Resumen ejecutivo con el conteo de issues por severidad (P0 a P3).
• Hallazgos detallados organizados por severidad, ubicación y categoría, con el impacto en el usuario, la referencia al estándar (WCAG u otro), una recomendación específica y el comando de Impeccable sugerido.

Fíjate en la diferencia clave con critique: aquí cada hallazgo cita un estándar verificable (por ejemplo, una violación concreta de WCAG en una ubicación concreta). No es una opinión sobre si “se siente genérico”, es un hecho medible. Por eso audit es ideal antes de una release: te da una lista de defectos técnicos que puedes marcar como resueltos uno a uno. Importante: audit reporta pero no arregla los problemas.

Ejemplo de invocación

/impeccable audit blog

El comando te devolverá la tabla de salud sobre 20, el resumen ejecutivo con los conteos por severidad y la lista priorizada de hallazgos. Al final, sugiere los próximos pasos ordenados por severidad, concluyendo con /impeccable polish e invitándote a re-auditar para rastrear la mejora.

La relación con el detector

Tanto critique como audit se apoyan en el detector del capítulo 4, pero lo usan distinto. El detector por sí solo es puramente determinista: ejecuta sus 44 reglas y reporta. audit y critique lo envuelven con el juicio del agente, que verifica cada hallazgo para descartar falsos positivos y lo enriquece con contexto, impacto y recomendaciones. El detector dice “esto coincide con la regla X”; el agente decide si eso realmente importa en este contexto y qué hacer al respecto.

polish: el pulido de los detalles finales

polish es el único de los tres que ejecuta cambios. No te entrega un informe para que decidas: hace una pasada meticulosa y final sobre la interfaz para cazar los detalles que separan el trabajo bueno del trabajo excelente. Su lema lo resume todo: “Polish is the last step, not the first.”

El requisito previo

Antes de pulir nada, polish hace una evaluación crítica: la funcionalidad debe estar completa. No tiene sentido ajustar el espaciado de un componente que aún no funciona. El comando primero revisa el nivel de completitud y la barra de calidad (¿es un MVP o una funcionalidad insignia?), piensa desde la perspectiva del usuario y separa lo cosmético de lo funcional antes de tocar una sola línea.

Qué pule, exactamente

polish aborda de forma sistemática:

• Visual y espaciado: alineación pixel-perfect, escalas de espaciado consistentes, adherencia a la grilla responsive.
• Arquitectura de la información: divulgación progresiva, flujos de usuario establecidos, consistencia de jerarquía y de nomenclatura.
• Tipografía: jerarquía, longitud de línea, kerning y carga de fuentes.
• Color y contraste: cumplimiento WCAG, uso de tokens, consistencia de tema.
• Estados de interacción: default, hover, focus, active, disabled, loading, error y success.
• Micro-interacciones: transiciones suaves (150-300 ms), easing apropiado y soporte de reduced-motion.
• Copy: consistencia de terminología, capitalización y gramática.
• Iconos e imágenes: consistencia de estilo, tamaño, alineación y texto alternativo.
• Formularios: labels, validación, orden de tabulación y mensajes de error.
• Casos límite: estados de carga, vacío, error y éxito.
• Responsividad: todos los breakpoints, áreas táctiles de mínimo 44x44 px.
• Calidad de código: sin console.log, sin imports sin usar, seguridad de tipos en TypeScript.

La alineación con el design system es innegociable

Hay una regla central en polish: “Aligning the feature to the design system is not optional.” Para cada desviación que encuentra, la clasifica antes de arreglarla en una de tres categorías:

• Token faltante: el valor existe en el sistema pero no se usó.
• Implementación one-off: se inventó un valor en lugar de usar el del sistema.
• Desalineación conceptual: el componente no encaja con los principios del sistema.

Esta clasificación importa porque no todos los arreglos son iguales: un token faltante se corrige sustituyendo un valor, pero una desalineación conceptual puede requerir repensar el componente. Aquí se conecta con el DESIGN.md que definiste en el capítulo 3: ese documento es la fuente de verdad contra la que polish mide cada desviación.

Ejemplo de invocación

/impeccable polish blog

A diferencia de critique y audit, no esperes un informe con tablas de puntuación: espera cambios aplicados en tus archivos, con una explicación de qué se ajustó y por qué. Por eso polish es siempre el último eslabón de la cadena, el que ejecutan los flujos de los otros comandos como paso de cierre.

Tabla comparativa

Aspecto	critique	audit	polish
Naturaleza	Opinión y dirección	Verificación sistemática	Ejecución de mejoras
¿Modifica código?	No	No	Sí
Base	Heurísticas + detector	Checklist técnica + detector	Design system + checklist
Salida	Informe priorizado (heurísticas de Nielsen, personas)	Informe técnico (5 dimensiones, WCAG)	Cambios aplicados
Puntuación	Design Health sobre 40	Audit Health sobre 20	No puntúa
Persistencia	Sí (.impeccable/critique/, con tendencia)	No	No
Cuándo usarlo	Para entender el rumbo del diseño	Antes de una release, para defectos técnicos	Al final, cuando todo funciona
Ejemplo	/impeccable critique blog	/impeccable audit blog	/impeccable polish blog

El flujo recomendado de revisión

Los tres comandos forman una secuencia natural. Primero entiendes el rumbo, luego verificas lo técnico, y al final pules:

sequenceDiagram
    participant D as Desarrollador
    participant C as critique
    participant A as audit
    participant P as polish
    D->>C: /impeccable critique blog
    C-->>D: Dirección + priority issues + tendencia
    D->>A: /impeccable audit blog
    A-->>D: Defectos técnicos verificables (WCAG, etc.)
    Note over D: Arregla los P0 y P1 con otros comandos
    D->>P: /impeccable polish blog
    P-->>D: Detalles finales aplicados

No es obligatorio ejecutar los tres siempre. Si solo quieres saber si tu diseño “se siente bien”, critique basta. Si vas a publicar y necesitas garantías de accesibilidad y performance, audit es el indicado. Y cuando la funcionalidad ya está completa y quieres ese último 5 % de calidad, polish cierra el trabajo. Lo importante es respetar el orden cuando los combinas: pulir antes de tener la dirección clara es desperdiciar esfuerzo.

Resumen

• critique emite un juicio de diseño honesto combinando una revisión holística (heurísticas de Nielsen, carga cognitiva, recorrido emocional, personas) con el escaneo del detector. Devuelve un Design Health Score sobre 40, priority issues con severidad P0-P3 y comandos sugeridos. Es el único que persiste sus resultados en .impeccable/critique/ mediante critique-storage.mjs, permitiendo rastrear la tendencia.
• audit realiza una verificación técnica sistemática en cinco dimensiones (accessibility, performance, responsive, theming, anti-patrones), puntuando sobre 20 y citando estándares verificables como WCAG. Reporta pero no arregla.
• polish es el único que ejecuta cambios: hace la pasada final sobre espaciado, alineación, microcopy, estados e interacciones, exigiendo que la funcionalidad esté completa y alineando todo al design system.
• La diferencia clave: critique da opinión y dirección, audit da una checklist objetiva, y polish ejecuta el pulido. Los tres se apoyan en el detector del capítulo 4, envolviéndolo con el juicio del agente.

Siguiente: Comandos de refinamiento: bolder, quieter, distill, harden