Solución de Problemas

Guia para diagnosticar y resolver problemas comunes con intake.

intake doctor

El primer paso ante cualquier problema es ejecutar intake doctor:

intake doctor

Esto verifica:

Check	Que verifica	Auto-fixable
Python version	Python >= 3.12	No
LLM API key	Variable de entorno configurada	No
pdfplumber	Paquete instalado	Si
python-docx	Paquete instalado	Si
beautifulsoup4	Paquete instalado	Si
markdownify	Paquete instalado	Si
litellm	Paquete instalado	Si
jinja2	Paquete instalado	Si
mcp package	Paquete `mcp` instalado (si mcp configurado)	Si
watchfiles	Paquete `watchfiles` instalado (si watch configurado)	Si
Config file	`.intake.yaml` valido	Si
Jira credentials	`JIRA_API_TOKEN` + `JIRA_EMAIL` (si jira configurado)	No
Confluence credentials	`CONFLUENCE_API_TOKEN` + `CONFLUENCE_EMAIL` (si confluence configurado)	No
GitHub token	`GITHUB_TOKEN` (si github configurado)	No
GitLab token	`GITLAB_TOKEN` (si gitlab configurado)	No

Auto-fix

Para corregir automaticamente los problemas que se pueden resolver:

intake doctor --fix

Esto:

Instala paquetes faltantes usando pip3.12, pip3 o pip (en ese orden de preferencia)
Crea .intake.yaml si no existe, con configuracion basica

Errores comunes

API key no configurada

Error:

LLM error: Environment variable ANTHROPIC_API_KEY is not set.
  Hint: Set it with: export ANTHROPIC_API_KEY=your-api-key

Solucion:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-api03-tu-key-aqui

# OpenAI
export OPENAI_API_KEY=sk-tu-key-aqui

Si usas otro proveedor, configura llm.api_key_env en .intake.yaml:

llm:
  model: gemini/gemini-pro
  api_key_env: GEMINI_API_KEY

Verifica con:

intake doctor

Archivo no encontrado

Error:

Failed to parse 'reqs.md': File not found: reqs.md
  Hint: Check that the file exists and the path is correct.

Solucion: Verifica que el path al archivo es correcto. Usa paths relativos al directorio actual o paths absolutos:

# Relativo
intake init "Feature" -s ./docs/reqs.md

# Absoluto
intake init "Feature" -s /home/user/project/docs/reqs.md

Archivo vacio

Error:

Failed to parse 'empty.md': File is empty or contains only whitespace
  Hint: Provide a file with actual content.

Solucion: El archivo existe pero no tiene contenido util. Agrega contenido al archivo antes de usarlo como fuente.

Archivo demasiado grande

Error:

Failed to parse 'huge.pdf': File size 52428800 bytes exceeds limit of 50 MB
  Hint: Split the file into smaller parts or extract the relevant sections.

Solucion: El limite es 50 MB. Opciones:

Dividir el archivo en partes mas pequenas
Extraer solo las secciones relevantes
Si es un PDF, extraer las paginas necesarias con otra herramienta

URL no accesible

Error:

Failed to parse 'https://example.com/page': Connection error: ...
  Hint: Check that the URL is correct and accessible.

Solucion: intake no pudo descargar la pagina. Verifica:

Que la URL es correcta y accesible desde tu red
Que no requiere autenticacion (intake no soporta URLs con login)
Que no hay un firewall o proxy bloqueando la conexion

Si la pagina requiere autenticacion, descarga el contenido manualmente y usa el archivo local:

# En vez de
intake init "Feature" -s https://internal-wiki.com/page  # falla si requiere login

# Descarga manualmente y usa el archivo
curl -o page.html https://internal-wiki.com/page
intake init "Feature" -s page.html

Conector no puede conectar

Error:

Connector error: Failed to connect to Jira at https://company.atlassian.net
  Hint: Check connectors.jira.url and credentials in .intake.yaml

Solucion:

Verificar que la URL base es correcta en .intake.yaml:

connectors:
  jira:
    url: "https://company.atlassian.net"

Verificar que las variables de entorno estan configuradas:

echo $JIRA_API_TOKEN    # debe tener un valor
echo $JIRA_EMAIL        # debe tener un valor

Ejecutar intake doctor para validar credenciales de conectores.
Si la API requiere VPN o firewall, verificar la conexion de red.

Conector: timeout o error de red

Error:

Connector error: Could not write temp file for ...: Connection timed out

Connector error: Could not access repository org/repo: ...

Solucion:

Timeout de red: verificar conexion a internet y que la API del servicio esta disponible:

# GitHub
curl -s https://api.github.com/rate_limit

# Jira
curl -s https://company.atlassian.net/rest/api/2/serverInfo

# Confluence
curl -s https://company.atlassian.net/wiki/rest/api/space

Token expirado o invalido: regenerar el token de acceso y actualizar la variable de entorno.
Repositorio o proyecto no encontrado: verificar que el nombre del repo/proyecto es correcto y que el token tiene permisos de lectura.
Disco lleno: si el error menciona “Could not write temp file”, verificar espacio en disco disponible.

Conector no disponible (dependencia faltante)

Error:

Connector 'jira' requires atlassian-python-api.
  Hint: Install with: pip install "intake-ai-cli[connectors]"

Solucion:

# Instalar dependencias de conectores
pip install "intake-ai-cli[connectors]"

Los paquetes opcionales para conectores son:

Conector	Paquete	Instalacion
Jira	atlassian-python-api	`pip install atlassian-python-api`
Confluence	atlassian-python-api	`pip install atlassian-python-api`
GitHub	PyGithub	`pip install PyGithub`
GitLab	python-gitlab	`pip install python-gitlab`

Alternativa sin instalar conectores: Exporta los datos manualmente:

Jira: Exporta issues como JSON desde la interfaz web
Confluence: Exporta la pagina como HTML
GitHub: Usa gh api repos/org/repo/issues > issues.json
GitLab: Usa curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/ID/issues" > issues.json

Formato no soportado

Error:

Unsupported format: 'xlsx' for source 'data.xlsx'

Solucion: intake no soporta archivos Excel directamente. Opciones:

Exportar a CSV o JSON desde Excel
Copiar el contenido a un archivo de texto o Markdown
Convertir a otro formato soportado (ver Formatos de entrada)

Presupuesto excedido

Error:

LLM error: Accumulated cost $0.5123 exceeds limit of $0.50
  Hint: Increase llm.max_cost_per_spec in your config, or use a cheaper model.

Solucion: El analisis supero el presupuesto configurado. Opciones:

Aumentar el limite:
```
llm:
  max_cost_per_spec: 1.00
```

Usar un modelo mas barato:

intake init "Feature" -s reqs.md -m gpt-3.5-turbo

Desactivar evaluacion de riesgos (ahorra ~30%):
```
spec:
  risk_assessment: false
```

Usar preset minimal:

intake init "Feature" -s reqs.md --preset minimal

LLM no retorna JSON valido

Error:

LLM error: LLM did not return valid JSON after 3 attempts
  Hint: Try a different model or simplify the prompt.

Solucion: El modelo no pudo generar JSON valido despues de los reintentos configurados. Opciones:

Intentar con otro modelo — algunos modelos son mejores generando JSON estructurado:
```
intake init "Feature" -s reqs.md -m claude-sonnet-4
```
Aumentar reintentos:
```
llm:
  max_retries: 5
```
Reducir la temperatura para output mas determinista:
```
llm:
  temperature: 0.1
```
Simplificar las fuentes — textos muy largos o complejos pueden confundir al modelo.

Timeout del LLM

Error:

LLM failed after 3 attempts: Request timed out
  Hint: Check your API key, network connection, and model name.

Solucion:

Verificar conexion a internet
Aumentar el timeout:
```
llm:
  timeout: 300  # 5 minutos
```

Verificar que el modelo existe — nombres incorrectos causan timeout:

# Correcto
llm:
  model: claude-sonnet-4

# Incorrecto — causara timeout o error
llm:
  model: claude-sonet-4  # typo

Error de encoding

Si un archivo tiene encoding no-UTF-8, intake intenta leerlo con fallback a latin-1. Si aun asi falla:

Solucion:

Convertir el archivo a UTF-8:

iconv -f ISO-8859-1 -t UTF-8 archivo.txt > archivo_utf8.txt

O abrir en un editor y guardar como UTF-8.

PDF sin texto extraible

Error:

Failed to parse 'scanned.pdf': PDF contains only scanned images, no extractable text
  Hint: Use an image source instead.

Solucion: El PDF contiene imagenes escaneadas, no texto digital. Opciones:

Usar OCR externo para extraer el texto primero
Exportar las paginas como imagenes y usar el parser de imagenes:
```
intake init "Feature" -s pagina1.png -s pagina2.png
```

Paquete faltante para parser

Error:

PDF parsing requires pdfplumber.
  Hint: Install it with: pip install pdfplumber

Solucion:

# Instalar manualmente
pip install pdfplumber

# O usar doctor --fix para instalar todo lo faltante
intake doctor --fix

Paquetes opcionales por parser:

Parser	Paquete	Instalacion
PDF	pdfplumber	`pip install pdfplumber`
DOCX	python-docx	`pip install python-docx`
Confluence	beautifulsoup4, markdownify	`pip install beautifulsoup4 markdownify`
URLs	httpx, beautifulsoup4, markdownify	`pip install httpx beautifulsoup4 markdownify`

Plugin no se carga

Error visible con:

intake plugins list -v   # La columna "Error" muestra el detalle
intake plugins check     # Reporta FAIL con detalles

Solucion:

Plugin externo no instalado: verifica que el paquete esta instalado en el mismo entorno:
```
pip list | grep mi-plugin
```
Entry point mal configurado: verifica que pyproject.toml tiene el entry_point correcto:
```
[project.entry-points."intake.parsers"]
mi-formato = "mi_plugin.parser:MiParser"
```
Error de importacion: el modulo del plugin falla al importar. Verifica las dependencias del plugin.
Reinstalar: a veces los entry_points no se actualizan sin reinstalar:
```
pip install -e .
```

Servidor MCP no arranca

Error:

ImportError: MCP server requires the mcp package. Install with: pip install intake-ai-cli[mcp]

Solucion:

pip install "intake-ai-cli[mcp]"

Si usas transporte SSE y falta starlette o uvicorn:

pip install starlette uvicorn

Puerto SSE ocupado:

Error: [Errno 98] Address already in use

Cambiar el puerto:

intake mcp serve --transport sse --port 9090

O en .intake.yaml:

mcp:
  sse_port: 9090

Watch mode no arranca

Error:

ImportError: Watch mode requires the watchfiles package. Install with: pip install intake-ai-cli[watch]

Solucion:

pip install "intake-ai-cli[watch]"

Spec directory no encontrado:

Watch error: Spec directory not found: specs/mi-feature
  Hint: Run 'intake init' first to generate a spec.

Verificar que el directorio de la spec existe y contiene acceptance.yaml.

acceptance.yaml no encontrado:

Watch error: acceptance.yaml not found in specs/mi-feature
  Hint: Run 'intake init' to generate acceptance.yaml.

Regenerar la spec con intake init o verificar que la spec fue generada en modo standard o enterprise (el modo quick no genera acceptance.yaml).

GitLab: error de conexion o autenticacion

Error:

Connector error: Failed to connect to GitLab at https://gitlab.company.com
  Hint: Check connectors.gitlab.url and GITLAB_TOKEN

Solucion:

Verificar que la URL es correcta en .intake.yaml:

connectors:
  gitlab:
    url: "https://gitlab.company.com"

Verificar que GITLAB_TOKEN tiene un valor:

echo $GITLAB_TOKEN   # debe tener un valor

El token necesita scope read_api minimo. Para issues privados, necesita api.
Para instancias self-hosted con certificados auto-firmados:
```
connectors:
  gitlab:
    ssl_verify: false
```
Ejecutar intake doctor para validar credenciales.

validate: errores de validacion

Error:

Validation failed: 3 issues found (1 error, 2 warnings)

Solucion: Esto no es un error de intake — es intake validate reportando problemas en la spec:

# Ver los detalles
intake validate specs/mi-feature/ --format json

# Modo estricto (warnings tambien son errores)
intake validate specs/mi-feature/ --strict

Problemas comunes que detecta:

Categoria	Ejemplo
`structure`	Falta `requirements.md` o `acceptance.yaml`
`cross_reference`	Una tarea referencia un requisito que no existe
`consistency`	Ciclos en dependencias de tareas
`acceptance`	Check sin comando definido
`completeness`	Requisito sin tarea que lo implemente

estimate: error al estimar

Error:

Error: No sources provided for estimation.

Solucion: intake estimate necesita al menos una fuente:

intake estimate -s requirements.md -s notas.md

Si el modelo no esta en la tabla de precios integrada, se usa el precio de claude-sonnet-4 como fallback. Puedes especificar el modelo:

intake estimate -s reqs.md --model gpt-4o

acceptance.yaml invalido

Error:

Verification failed: Invalid YAML in acceptance.yaml: ...
  Hint: Check acceptance.yaml syntax.

Solucion: El archivo acceptance.yaml tiene errores de sintaxis YAML. Verificar:

Indentacion correcta (usar espacios, no tabs)
Strings con caracteres especiales entre comillas
Listas con - seguido de espacio

# Correcto
checks:
  - id: check-01
    name: "Tests pasan"
    type: command
    command: "python -m pytest tests/ -q"

# Incorrecto — falta espacio despues de -
checks:
  -id: check-01

FAQ

Necesito internet para usar intake?

Solo para intake init y intake add (que requieren llamadas al LLM). Todo lo demas funciona offline:

intake verify — ejecuta checks localmente
intake export — genera archivos localmente
intake show / intake list — lee archivos locales
intake diff — compara archivos locales
intake doctor — verifica el entorno local
intake validate — valida consistencia interna de la spec
intake estimate — estima costo (usa tabla local de precios)
intake mcp serve — ejecuta el servidor MCP localmente
intake watch — monitorea archivos y re-verifica localmente

Puedo usar modelos locales?

Si. intake usa LiteLLM, que soporta modelos locales via Ollama, vLLM, y otros:

llm:
  model: ollama/llama3
  api_key_env: DUMMY_KEY  # Ollama no necesita key

export DUMMY_KEY=not-needed
intake init "Feature" -s reqs.md

En que idioma se genera la spec?

Por defecto en ingles (en). Se configura con --lang o project.language:

intake init "Feature" -s reqs.md --lang es

project:
  language: es

El idioma afecta al contenido generado por el LLM, no a la estructura de los archivos.

Cuanto cuesta generar una spec?

Depende del modelo, la cantidad de texto, y las opciones habilitadas:

Escenario	Costo aproximado
Fuente pequena, preset minimal, Claude Sonnet	~$0.02-0.05
Fuente mediana, preset standard, Claude Sonnet	~$0.05-0.15
Multiples fuentes, preset enterprise, Claude Sonnet	~$0.15-0.50
GPT-3.5 en vez de Claude	~50-70% menos

Usa intake show para ver el costo real despues de generar.

Puedo editar las specs generadas?

Si. Las specs son archivos Markdown y YAML normales. Puedes editarlos manualmente despues de generarlos. Sin embargo, si usas intake add --regenerate, tus ediciones manuales se sobreescribiran.

Como actualizo una spec con nuevos requisitos?

# Agregar una fuente nueva
intake add specs/mi-feature/ -s nuevos-reqs.md

# O regenerar todo con la nueva fuente
intake add specs/mi-feature/ -s nuevos-reqs.md --regenerate

Puedo usar intake en CI/CD?

Si. Ver la seccion de integracion CI/CD en la guia de verificacion.

Los archivos spec se deben commitear a git?

Si, es recomendable. Las specs son archivos de texto que se benefician del versionado. Ver Versionado de specs.

Que es el modo quick / standard / enterprise?

intake auto-detecta la complejidad de tus fuentes y selecciona un modo de generacion:

quick (<500 palabras, 1 fuente simple): solo genera context.md + tasks.md
standard (default): genera los 6 archivos spec completos
enterprise (4+ fuentes o >5000 palabras): todos los archivos + riesgos detallados

Puedes forzar un modo con --mode:

intake init "Fix rapido" -s bug.txt --mode quick

Como instalo plugins externos?

Los plugins se descubren automaticamente al instalar paquetes que registran entry_points en los grupos intake.parsers, intake.exporters, o intake.connectors:

pip install mi-plugin-intake
intake plugins list   # deberia aparecer el nuevo plugin

Ver Plugins para mas detalles.

Como veo el progreso de las tareas?

intake task list specs/mi-feature/
intake task update specs/mi-feature/ 1 done --note "Completado"