gtarpenning/ui-critic

¿Qué hace ui-critic?

Juzga pantallas de la misma manera que lo haría una persona específica, usando sus decisiones pasadas como evidencia. Claude sin personalizar obtuvo un 44-50% de acierto al predecir las elecciones reales de diseño de esta persona, y este procedimiento alrededor del 60%, en decisiones sobre las que no tenía evidencia del mismo tema (resultados). Es una segunda opinión sólida, no un oráculo.

Pregunta	Acción
¿Qué diseño es mejor?	Comparar
¿Qué debería cambiar en esta pantalla o flujo?	Criticar
Enséñale, ajústalo, se equivocó en esto	Ajustar
La persona acaba de decidir entre diseños	Registrar una decisión

Los scripts viven junto a este archivo. Ejecútalos con python3; prepare.py y annotate.py necesitan Pillow (pip install pillow).

Siempre

• Entiende primero la tarea. Si no sabes para qué es la pantalla ni para quién, pregunta una vez. Si no, indica tu suposición.
• Las decisiones pasadas están por encima de estas reglas y de la opinión general de diseño. Lo más nuevo prevalece sobre lo más antiguo.
• No razones solo desde las "mejores prácticas". El razonamiento general cuidadoso obtuvo un rendimiento por debajo del azar en las decisiones de esta persona, porque tiende a argumentar a favor de más información, etiquetas y números. Argumenta basándote en lo que realmente eligieron.
• No generalices una preferencia más allá de su evidencia. "Menos" en una lista no significa "menos" en todas partes. Eligieron una imagen de mapa sobre un chip de texto más corto, y añadieron fotos y notas en un paso de comparación, porque esas cosas permiten reconocer elementos más rápido.
• Empieza con la respuesta. Veredicto primero, luego detalle. Tu informe sigue la misma revelación progresiva que estás juzgando.

Comparar

1. Preparar. python3 scripts/prepare.py --out <tmp> <imágenes...>, luego usa las copias preparadas. Para un flujo, cada diseño es una lista ordenada de pantallas.

2. Obtener evidencia. Lee taste/taste.md. Ejecuta python3 scripts/cases.py --context "<para qué es esta pantalla>" --k 4.

3. Juzgar dos veces, a ciegas. Crea dos subagentes sin contexto compartido, usando el prompt en references/judge.md. Uno ve los diseños en orden X, Y etiquetados A, B; el otro ve Y, X. Usa Sonnet: Opus costó varias veces más y no obtuvo mejores resultados. Dale a cada uno las rutas de las imágenes de los casos y dile que Lea cada imagen. No les digas qué diseño prefieres tú, quién hizo cuál, ni cuál es más reciente.

   Más de dos diseños: compara los dos que parezcan más fuertes por pares, luego el ganador contra el siguiente. No pidas una clasificación en una sola ronda.

4. Decidir.

   • Ambos eligen el mismo diseño: ese es el veredicto.
   • Discrepan: di demasiado reñido para decidir, presenta el mejor argumento de cada lado en una línea, y nombra la pregunta decisiva para la persona. No rompas el empate tú mismo.

5. Mirar más allá de las opciones. Si ambos diseños comparten un defecto, o el perdedor tiene una idea que vale la pena conservar, propón la versión combinada en una o dos frases. A menudo los ganadores anteriores surgieron exactamente de esto.

6. Informar.

   **B.** <una frase: la diferencia que lo decide.>
   Confianza: ambos órdenes coincidieron (no es una prueba: otro modelo o evidencia aún puede cambiarlo) / demasiado reñido para decidir
   - Por qué: <las diferencias decisivas, citando las decisiones pasadas que reflejan>
   - Vale la pena conservar de A: <si hay algo>
   - Mejor que ambos: <si lo hay>
   

   Añade una superposición con recuadros de los problemas restantes del ganador solo si te lo piden.

Criticar

1. Preparar las pantallas como arriba, y anota el tamaño en píxeles de cada una. Las coordenadas solo coinciden en las copias preparadas.
2. Obtener evidencia. Lee taste/taste.md y ejecuta cases.py --k 4, luego Lee ambas imágenes de cada caso antes de mirar las nuevas pantallas. Las puntuaciones a continuación asumen que las viste.
3. Revisar, en este orden:
   • ¿Cuál es la única razón por la que alguien viene a esta pantalla? ¿Qué debe captar de un vistazo?
   • Revisa elemento por elemento: ¿merece su lugar aquí, o podría estar a un toque de distancia? ¿Se dice algo dos veces? ¿El mismo tipo de cosa está dibujado de dos formas diferentes, en esta pantalla o en otra parte de la aplicación? ¿Una segunda acción compite con la principal? ¿Se entendería una imagen más rápido que las palabras?
   • Para un flujo, también pregúntate: ¿lo que se abre se parece a lo que tocaste? ¿Algún paso es un callejón sin salida?
4. Recortar. Como máximo 3 hallazgos, del más importante al menos. Omite accesibilidad genérica, pulido estándar y cualquier cosa a la que no puedas señalar. Si el diseño es bueno, dilo y no reportes nada. Rellenar con problemas menores es un fracaso. Antes de terminar, verifica que cada hallazgo no deshaga una decisión pasada.
5. Dibujar. Escribe findings.json junto a las pantallas preparadas, con recuadros como píxeles absolutos ajustados [x1, y1, x2, y2] sobre la copia preparada:

   {"verdict": "Una frase.",
    "screens": [{"path": "/abs/prepared.png", "label": "Inicio"}],
    "findings": [{"screen": 0, "box": [40, 120, 300, 180], "severity": "alta", "title": "...", "why": "...", "fix": "..."}]}
   

   Ejecuta python3 scripts/annotate.py findings.json --out <tmp>. Lee cada .annotated.png y verifica que cada recuadro esté sobre lo que describe su hallazgo. Si alguno está desplazado, corrige los números y vuelve a ejecutar. Un recuadro alrededor de una tarjeta completa está bien cuando el hallazgo trata sobre la tarjeta.
6. Informar el veredicto, los hallazgos y las rutas a report.html y las imágenes anotadas.

Registrar una decisión

Cuando la persona elige entre diseños o expresa una preferencia mientras mira pantallas, ofrécete a registrarlo: python3 scripts/record.py --context "..." --winner a.png --loser b.png --reason "sus palabras" --topic <slug-corto>. Usa sus palabras para la razón. Así es como mejora el skill, y una frase de "por qué" vale más que varias elecciones sin explicación.

Ajustar

Inicia python3 scripts/tune.py, ejecútalo en segundo plano, y dale a la persona la URL. Tiene cuatro pestañas:

• Elegir: elige entre diseños con las teclas de flecha. Unos 5 minutos.
• Errores: donde el juez discrepa de la persona, y su argumento. La persona mantiene su decisión o dice que el juez tiene razón.
• Reglas: edita taste/taste.md.
• Puntuación: reevalúa, incluyendo cuán consistentes son las propias elecciones de la persona.

Después de las elecciones o ediciones, ejecuta python3 scripts/distill.py para reconstruir taste/taste.md a partir de todas las decisiones. Consulta references/tuning.md para los números y para usar esto con el gusto de otra persona.