docker-compose-doctor

Diagnostica problemas comunes en archivos compose.yml / docker-compose.yml antes de hacer docker compose up — para que el stack levante a la primera y los servicios queden saludables.

No reemplaza a docker compose config (que valida sintaxis del schema). Cubre la capa de convenciones operacionales que el schema oficial no captura: healthchecks faltantes, dependencias sin esperar a service_healthy, etc.

Cuándo invocar este skill

Triggers explícitos:

• "revisa el compose"
• "valida docker-compose"
• "qué tiene mal este compose"
• "docker compose lint"
• "auditar compose.yml"
• "chequea el stack"
• "por qué no levanta este compose"
• "doctor del compose"

Triggers proactivos:

• Después de editar cualquier compose*.y*ml o docker-compose*.y*ml en la sesión.
• Antes de un docker compose up cuando el usuario menciona problemas de orden de arranque, servicios "unhealthy", o puertos en conflicto.

Cómo se invoca

Sin argumentos: busca compose.yml, compose.yaml, docker-compose.yml y docker-compose.yaml en Path.cwd() recursivamente hasta 3 niveles.

python ~/.agents/skills/docker-compose-doctor/docker_compose_doctor.py

Modos:

# Archivo específico
python .../docker_compose_doctor.py path/to/compose.yml

# Solo errores (omite warnings)
python .../docker_compose_doctor.py --errors-only

# Output JSON (para integraciones)
python .../docker_compose_doctor.py --json

# Verbose — muestra cada check ejecutado
python .../docker_compose_doctor.py -v

Exit codes:

• 0 — sin hallazgos o solo warnings.
• 1 — al menos un error (bloquea CI / pre-push).
• 2 — error de invocación (archivo no existe, YAML malformado).

Qué chequea exactamente

Qué NO hace / limitaciones

• No valida el schema de Compose. Para eso usa docker compose config -q — este skill asume que la sintaxis ya es válida.
• No ejecuta el stack. Es análisis estático del YAML; no detecta problemas que solo aparecen runtime (ej. health check que devuelve 200 pero la app está rota internamente).
• No resuelve ${VAR} con valores de entorno. Si tu image: ${MY_IMAGE} no tiene tag literal en el YAML, no se reporta como latest — porque no se sabe.
• No valida redes custom. Salir del scope MVP — puede llegar en una versión futura.
• Sigue extends: y include: solo a un nivel (en compose v2.20+). Composes muy anidados pueden tener falsos negativos.

Dependencias

Sin binarios externos. No invoca docker ni docker compose.

Ejemplos de salida

Caso con hallazgos

docker-compose-doctor — repo: /ruta/a/mi-proyecto
  archivo: compose.yml (5 servicios)

[errors]
  ✗ Puerto host 8080 duplicado entre servicios 'api' y 'admin'
    api:    "8080:8000"  (línea 14)
    admin:  "8080:80"    (línea 41)
  ✗ env_file inexistente en servicio 'worker': ./envs/worker.env (línea 67)

[warnings]
  ⚠ Servicio 'api' sin healthcheck — depends_on no podrá esperar a service_healthy
  ⚠ Servicio 'worker' depende de 'db' (que tiene healthcheck) con depends_on simple
    Sugerencia:
        depends_on:
          db:
            condition: service_healthy
  ⚠ Imagen 'redis' sin tag (línea 52) — pinnea a 'redis:7.2-alpine' o similar
  ⚠ Volumen 'old_cache' declarado pero no referenciado por ningún servicio

Resumen: 2 errores, 4 warnings.

Exit 1 (errores presentes).

Caso limpio

docker-compose-doctor — repo: /ruta/a/mi-proyecto
  archivo: compose.yml (5 servicios)

✓ Puertos: sin conflictos
✓ Healthchecks: 5/5 servicios cubiertos
✓ depends_on: todas las dependencias usan condition apropiada
✓ Imágenes: todas pinneadas
✓ Volúmenes: sin huérfanos
✓ env_file: todos los archivos existen

Resumen: 0 errores, 0 warnings. OK para `docker compose up`.

Exit 0.

Integración con flujo de trabajo

Combinable con [[yaml-control]] (valida sintaxis YAML del compose) y [[pre-push-guard]] (orquesta ambos + tests antes de pushear).

# Antes de un cambio importante al stack
python ~/.agents/skills/yaml-control/yaml_control.py
python ~/.agents/skills/docker-compose-doctor/docker_compose_doctor.py
docker compose up -d