Troubleshooting
Esta sección recoge problemas comunes y una primera forma de diagnosticarlos.
La IA no entiende el proyecto
Sección titulada «La IA no entiende el proyecto»Posibles causas:
- Falta
AGENTS.md. - La arquitectura no está documentada.
- Las convenciones no coinciden con el código real.
- El prompt pide demasiado sin contexto.
Primer paso recomendado: revisar contexto de proyecto antes de repetir la instrucción con más texto.
La spec no reduce ambigüedad
Sección titulada «La spec no reduce ambigüedad»Posibles causas:
- Resume la necesidad, pero no define criterios.
- No explicita supuestos.
- No identifica riesgos.
- No traduce la petición en tareas ejecutables.
Primer paso recomendado: volver al Spec Author y pedir reconciliación de spec antes de implementar.
El MCP aparece conectado pero no devuelve lo esperado
Sección titulada «El MCP aparece conectado pero no devuelve lo esperado»Posibles causas:
- Permisos insuficientes.
- Enlace incorrecto.
- Recurso privado para otra cuenta.
- El MCP no tiene acceso a esa parte de la herramienta.
Primer paso recomendado: probar una consulta simple y verificar que el recurso existe para la cuenta conectada.
Diseño y código no encajan
Sección titulada «Diseño y código no encajan»Posibles causas:
- No se han extraído foundations.
- Faltan variantes o estados.
- El componente del proyecto ya tiene restricciones no reflejadas en diseño.
- Se está usando una fuente o nodo incorrecto.
Primer paso recomendado: capturar evidencia y separar diferencia visual, diferencia funcional y restricción técnica.
El plan es demasiado grande
Sección titulada «El plan es demasiado grande»Posibles causas:
- La necesidad agrupa demasiadas decisiones.
- La IA ha creado tareas con alcance amplio.
- No se han identificado dependencias.
Primer paso recomendado: partir tasks.md en unidades más pequeñas y marcar bloqueos.
Los checks fallan
Sección titulada «Los checks fallan»Posibles causas:
- El cambio rompió comportamiento.
- Hay deuda preexistente.
- El entorno local no está preparado.
- Un guardarraíl no estaba contemplado.
Primer paso recomendado: clasificar el fallo antes de seguir editando.
La skill produce resultados inconsistentes
Sección titulada «La skill produce resultados inconsistentes»Posibles causas:
- La skill es demasiado genérica.
- No define salidas.
- No indica validaciones.
- Depende de contexto que no existe en el proyecto.
Primer paso recomendado: concretar entradas, pasos y criterio de salida.
Default recomendado
Sección titulada «Default recomendado»No resuelvas problemas recurrentes solo con prompts más largos. Si el problema se repite, conviértelo en contexto, proceso, skill o regla explícita.