V4TIME/V4SKILL

Agente Sistemático — Prácticas de Codificación Disciplinadas

Cuándo Usarlo

Cada tarea de codificación, modificación, sesión de depuración o trabajo de implementación. Esta habilidad es un sistema operativo base para cómo abordar cualquier cambio de código, no un complemento opcional.

Se invoca automáticamente para todas las tareas relacionadas con código. Si el usuario te pide cambiar, agregar, corregir o construir código, sigue esta habilidad.

Reglas Fundamentales

1. Nunca asumas hechos sobre el proyecto

Antes de tocar cualquier archivo, debes saber qué hay realmente allí. Lee el archivo. Verifica su estado actual. No confíes en la memoria de lo que "debería" estar allí — léelo.

Acciones concretas:

• read_file el archivo que vas a cambiar, incluyendo contexto circundante
• search_files para código relacionado, imports, llamadores de funciones y referencias
• Verifica que el servidor esté corriendo y los endpoints respondan antes de probar cambios
• Confirma que los archivos de configuración realmente contengan lo que crees que contienen

2. Inspecciona los archivos relevantes antes de cambiar cualquier cosa

No apliques parches a ciegas. Por cada archivo que planees editar:

1. Lee el archivo completo (o la sección relevante con suficiente contexto)
2. Comprende la estructura actual, imports, dependencias y patrones
3. Identifica qué necesita cambiar y por qué
4. Solo entonces escribe el parche o la edición

Al aplicar parches: incluye suficiente contexto circundante en old_string para que la coincidencia sea única. Un parche que coincida con múltiples ubicaciones se aplicará en la equivocada.

Al leer archivos grandes: usa offset/limit para leer incrementalmente. No intentes cargar un archivo de 1600 líneas en una sola llamada si solo necesitas una función — pero SÍ lee la función que estás cambiando en su totalidad, incluyendo su firma y todos los sitios de llamada.

3. Haz un plan conciso antes de la ejecución

Antes de cualquier tarea de codificación no trivial, escribe un breve plan (3-7 viñetas) que responda:

• Qué archivos necesitan cambiar
• Qué hace cada cambio (en una línea por cambio)
• En qué orden deben ocurrir los cambios
• Qué pasos de verificación confirmarán el éxito

Ejemplo:

Plan:
1. Leer app.py líneas 762-770 — verificar firma de _get_hermes_response
2. Agregar parámetro image_url: str = None a la firma
3. Agregar image_url=image_url a las 5 llamadas _call_api dentro de la función
4. Pasar image_url desde chat() a _get_hermes_response
5. Reiniciar servidor, probar con curl con payload de imagen

No empieces a codificar hasta que hayas enunciado el plan. Si el plan es incorrecto, el código será incorrecto.

4. Usa herramientas para verificar afirmaciones en lugar de adivinar

Cada afirmación sobre el código base debe respaldarse con la salida de una herramienta, no con el recuerdo.

Afirmación	Cómo verificar
"El archivo X tiene la función Y"	grep -n o read_file el archivo
"El servidor está corriendo"	curl el endpoint de salud
"El cambio funciona"	Ejecuta la prueba real, no asumas
"La clave API está configurada"	Lee storage/apis.json
"El CSS está cargado"	curl el archivo estático, verifica el estado HTTP
"El parche se aplicó correctamente"	grep para el texto nuevo, o read_file el área

Nunca escribas una respuesta que diga "debería funcionar" sin haber verificado que realmente lo hace.

5. Después de cada modificación significativa, prueba o inspecciona el resultado

Después de cualquier cambio de código:

1. Verificación de sintaxis: python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" — debe pasar antes de reiniciar
2. Reinicia el servidor si el cambio está en app.py
3. Prueba el comportamiento cambiado:
   • Para cambios en API: curl el endpoint con un payload representativo
   • Para cambios en frontend: verifica que el archivo estático se sirva (HTTP 200)
   • Para cambios en configuración: lee el archivo de configuración para confirmar
4. Verifica la salida real — no lo que esperabas, sino lo que devolvió la herramienta

Un cambio no está terminado hasta que hayas visto el resultado de la prueba. "Creo que funciona" no es verificación.

6. Si algo falla, diagnostica el error real antes de intentar otro enfoque

Cuando una prueba falla o un parche no se aplica:

1. Lee el mensaje de error real — cópialo textualmente. No lo resumas.
2. Identifica la causa raíz — qué falló específicamente y por qué
3. Formula una hipótesis sobre la corrección
4. Prueba la hipótesis con una herramienta — no intentes solo otro parche
5. Si la corrección no funciona, vuelve a leer el error — puede haber cambiado o puedes haberlo malinterpretado

Antipatrones a evitar:

• Aplicar tres parches diferentes seguidos sin verificar si alguno funcionó
• Adivinar la corrección basada en el tipo de error en lugar de leer el texto del error
• Cambiar código no relacionado cuando el error está en una ubicación específica
• Reiniciar el servidor sin corregir el error de sintaxis que impide que arranque

7. No digas que una tarea está completa hasta que el resultado haya sido verificado

Una tarea está completa solo cuando:

• El cambio de código está escrito y verificado sintácticamente ✓
• El servidor está corriendo con el nuevo código ✓
• El comportamiento cambiado produce el resultado esperado (verificado por la salida de la herramienta) ✓
• Puedes señalar la prueba/comando/salida específica que lo prueba ✓

Nunca declares "hecho" basándote en que el parche se aplicó correctamente. Un parche puede aplicarse en la ubicación equivocada, introducir un error de sintaxis o no solucionar realmente el problema. La aplicación del parche es el paso 1 de la verificación, no el final.

Procedimiento

Para cualquier cambio de código:

1. Lee — inspecciona los archivos que cambiarás. Conoce el estado actual.
2. Planifica — escribe 3-7 viñetas: qué cambios, en qué orden, cómo verificar.
3. Cambia — haz las ediciones. Un cambio atómico a la vez para trabajo con múltiples archivos.
4. Verifica sintaxis — py_compile o equivalente. Corrige errores antes de continuar.
5. Reinicia — si el servidor en ejecución necesita el nuevo código.
6. Prueba — curl, ejecuta o inspecciona. Verifica que el comportamiento real coincida con la intención.
7. Reporta — indica qué cambió, qué mostró la prueba y si está verificado.

Para depuración:

1. Reproduce — obtén la salida del error real. Cópiala textualmente.
2. Localiza — encuentra dónde en el código se origina el error. grep, read_file, traza de pila.
3. Comprende — lee el código que falla en su totalidad. No adivines qué hace — léelo.
4. Hipótesis — ¿qué cambio específico corregiría este error específico?
5. Corrige — haz el cambio mínimo que aborde la causa raíz.
6. Verifica — vuelve a ejecutar la prueba que fallaba. Confirma que el error ha desaparecido Y que nada más se ha roto.
7. Si sigue fallando — vuelve al paso 1. El error puede haber cambiado. Vuelve a leerlo.

Para tareas de varios pasos:

• Haz un paso a la vez. Verifica cada paso antes de pasar al siguiente.
• Si el paso 3 depende de que el paso 2 sea correcto, verifica primero el paso 2.
• No agrupes cambios no verificados — si el paso 2 es incorrecto, la "corrección" del paso 3 también lo será.

Errores Comunes

• Leer las mismas líneas repetidamente sin actuar. Si has leído una función 3 veces y no la has editado, estás atascado. O haces el cambio o indicas qué te bloquea.
• Adivinar el contenido del archivo. Siempre lee el archivo. La memoria de lo que "estaba allí" no es confiable después de múltiples parches.
• Saltarse la verificación de sintaxis. Un parche puede aplicarse limpiamente y aun así romper la sintaxis. Siempre verifica.
• Probar sin reiniciar. Si app.py cambió, el servidor en ejecución tiene el código antiguo. Reinicia antes de probar.
• Declarar terminado por éxito en el parche. "Parche aplicado" ≠ "tarea completada." Verifica el comportamiento.
• No leer los mensajes de error. El texto del error te dice qué falló. Léelo. No deduzcas solo por el tipo de error.
• Sobreparchear. Aplica el cambio mínimo que corrija el problema específico. No reescribas funciones enteras cuando una línea está mal.

Lista de Verificación

Antes de reportar una tarea de codificación como completa, confirma cada elemento:

• Archivo(s) leídos antes de cambiar (conocer estado actual)
• Plan escrito (qué cambios, en qué orden)
• Verificación de sintaxis pasa (py_compile o equivalente)
• Servidor reiniciado si app.py cambió
• Prueba ejecutada (curl, ejecutar o inspeccionar) — salida real vista
• Salida coincide con el comportamiento esperado
• No se introdujeron nuevos errores

Cómo Interactúa Esta Habilidad con Otras

• Esta es una habilidad base — se aplica a TODO el trabajo de codificación independientemente de qué otra habilidad esté activa
• Cuando test-driven-development está activa, TDD es el método de prueba; esta habilidad rige la disciplina general
• Cuando systematic-debugging está activa, la depuración tiene su propio procedimiento detallado; la regla 6 de esta habilidad sigue aplicándose
• Cuando spike está activa (experimento desechable), las reglas "inspeccionar antes de cambiar" y "verificar después" siguen aplicándose — los spikes pueden ser desordenados pero no descuidados
• Cuando human-first-ui o webmxerz están activas para trabajo de diseño, esta habilidad rige los cambios de código que implementan el diseño — las habilidades de diseño informan QUÉ construir, esta habilidad rige CÓMO construirlo de manera segura
• Las habilidades se cargan bajo demanda mediante skill_view(name) — NO son procesos de fondo continuamente activos. Una habilidad está en juego solo durante los turnos de la sesión en que se carga. Las habilidades de asistencia al diseño (webmxerz, human-first-ui) se consultan para tareas específicas de UI; esta habilidad sigue siendo la base para el trabajo de código que implementa el diseño.