cucuwang/visual-fix

Corrección Visual (Visual Fix)

Convierte un problema visible de UI en un cambio de código localizado, aprobado y verificado.

Evidencia admitida

Acepta cualquier combinación útil de:

• Una captura de pantalla de la UI actual
• Una región anotada o descrita dentro de una captura
• Una captura de pantalla actual y otra objetivo con sus roles identificados
• Una ruta, viewport, nombre de componente, texto visible, selector o identificador de prueba
• Un síntoma en lenguaje natural como "esta tarjeta está recortada" o "estos controles no están alineados"

Solicita solo evidencia que impida la localización confiable. Una ruta más un texto visible único pueden ser suficientes sin necesidad de captura de pantalla. Una captura de pantalla con componentes repetidos puede seguir necesitando una ruta, etiqueta o estado.

Maneja un problema visual a la vez. Divide los síntomas no relacionados en correcciones separadas.

Flujo de trabajo

1. Establecer el objetivo

Reformula el resultado acotado en términos concretos:

• Qué se ve mal actualmente
• Qué espera ver el usuario
• Qué ruta, componente, estado y viewport son relevantes cuando se conozcan
• Qué ancla visible identifica el objetivo

Si el resultado solicitado es subjetivo o podría afectar diferentes elementos, haz la pregunta más pequeña que los distinga.

2. Establecer una línea base de solo lectura

Antes de editar:

• Encuentra las instrucciones del repositorio y la fuente de verdad.
• Inspecciona el estado del worktree y conserva los cambios existentes del usuario.
• Identifica el framework, la entrada de ruta, el árbol de componentes, el sistema de estilos y los comandos de ejecución o prueba disponibles.
• Reproduce la ruta y el viewport objetivo cuando el entorno lo permita.
• Captura o registra el estado actual antes de modificarlo.

No edites la salida generada cuando exista un archivo fuente mantenido. No limpies ni sobrescribas cambios no relacionados en el worktree.

Reporta brevemente la línea base:

Contexto
- Ruta/estado: /catalog, filtros abiertos
- Viewport: 390 x 844
- Fuente de verdad: src/routes/catalog.tsx + src/styles/catalog.css
- Cambios de usuario existentes: ninguno
- Reproducción: disponible

3. Localizar la fuente renderizada

Rastrea la evidencia desde el elemento renderizado hasta el código mantenido. Usa la ruta, el nombre accesible, el texto visible, el selector DOM, el nombre del componente, el identificador de prueba, la clase, el token de estilo o la geometría de la captura de pantalla. Lee references/locating.md cuando haya múltiples archivos o capas de estilo involucradas.

Identifica una ubicación de fuente principal y como máximo dos ubicaciones relacionadas requeridas. La evidencia de archivo y línea debe provenir del worktree actual.

Localizado
- Principal: src/components/ProductGrid.tsx:42, ProductGrid
- Relacionado: src/styles/products.css:18
- Evidencia: `.grid` controla el espaciado horizontal repetido visible entre las tarjetas
- Confianza: alta

Si dos elementos similares siguen siendo plausibles, explica la evidencia distintiva y detente para aclaración.

4. Diagnosticar a partir de la evidencia

Conecta el síntoma visible con el código real. Prefiere una causa respaldada. Ofrece dos o tres hipótesis solo cuando la evidencia siga siendo ambigua.

Para cada hipótesis incluye:

• La propiedad, selector, token o componente involucrado
• El código o evidencia renderizada que lo respalda
• La dirección de corrección prevista
• Una observación que lo refutaría

No inventes valores CSS a partir de la captura de pantalla. Inspecciona primero el valor actual y el sistema de diseño circundante.

5. Presentar el plan de cambio exacto

Muestra el parche propuesto antes de editar:

Plan de cambio
- Archivos: src/components/ProductGrid.tsx:42
- Actual: gap: 8px
- Propuesto: usar el token space-4 existente (16px)
- Alcance: ProductGrid en /catalog y /search
- Conservando: padding de tarjetas, número de columnas en móvil, rutas no relacionadas
- Verificación: prueba dirigida, lint, capturas a 390 x 844 y 1280 x 800
- Riesgo: medio; el componente es compartido por dos rutas

Espera la aprobación explícita de este plan. Elegir un diagnóstico no aprueba un cambio de código. Si luego el plan se expande a otro archivo, dependencia, archivo de bloqueo, artefacto generado o ruta, presenta el plan revisado y obtén aprobación nuevamente.

6. Aplicar el parche aprobado

Realiza el cambio más pequeño que implemente el plan. Mantén las ediciones dentro de los archivos y el alcance aprobados. Luego inspecciona el diff inmediatamente:

• Ejecuta git diff --check cuando el proyecto use Git.
• Confirma que el diff contiene solo el cambio planeado.
• Conserva los cambios preexistentes y evita cambios de formato no relacionados.
• No hagas commit, push, instales dependencias ni modifiques servicios externos a menos que esté autorizado por separado.

7. Verificar el resultado

Lee references/verification.md antes de afirmar éxito.

Usa la evidencia más sólida disponible:

1. Ejecuta pruebas dirigidas, formato, verificaciones de tipos o una compilación relevante para el código modificado.
2. Renderiza la misma ruta, estado y viewport utilizados para la línea base.
3. Compara visualmente antes y después.
4. Verifica un viewport cercano o ruta compartida cuando la fuente modificada tenga un alcance más amplio.

Reporta exactamente un estado de verificación:

• Verificado visualmente cuando exista evidencia de renderizado comparable antes y después
• Verificado estáticamente cuando las comprobaciones de código pasen pero la UI no se haya podido renderizar
• No se puede verificar visualmente cuando el entorno carezca de la ruta, navegador, fixture o ruta de inicio
• Verificación fallida con el comando fallido o regresión observada

Si la verificación falla, regresa al diagnóstico. No apiles una segunda corrección no aprobada sobre la primera.

Informe de finalización

Mantén la entrega compacta y basada en evidencia:

Corregido
- Objetivo: espaciado de tarjetas del catálogo en ancho móvil
- Fuente: src/components/ProductGrid.tsx:42
- Cambio: gap ahora usa space-4
- Verificación: Verificado visualmente a 390 x 844; prueba unitaria y lint pasaron
- Verificaciones adicionales: /search a 390 x 844 y /catalog a 1280 x 800

Menciona cualquier incertidumbre visual restante. Nunca describas un diff de código como prueba visual.