planificar

name	planificar
description	Metodología de planificación para el bucle ralph en AbadIA-MCP — granularidad, estructura de tareas y prerrequisitos
metadata	{"tipo":"metodologia"}

Granularidad

Cada tarea (plan/task/NN.md) documenta un único módulo del vault o una pasada de grafo. Las subtareas son atómicas: una acción ejecutable por iteración (leer ficheros, generar una sección, actualizar config, ejecutar validate).

Estructura canónica de una tarea de módulo vault

1. Subtarea [esfuerzo low] — cambiar capacidad a low, validar contexto.
2. Subtarea [esfuerzo med] — inventario de ficheros fuente + cambiar capacidad a med.
3. Subtarea [esfuerzo high] — generar secciones vault + cambiar capacidad a high.
4. Checkpoint [juez] — verificar secciones generadas.
5. Subtarea — crear README índice y repo-card tier-1.
6. Subtarea — stampar frontmatter de provenance.
7. Subtarea — ejecutar gv.py validate Y actualizar config con phase: done + last_sync_commit (estas dos acciones son inseparables en la misma subtarea).
8. Checkpoint [juez] — verificar README, repo-card, frontmatter, validación y cierre de config.
9. Subtarea — /maestro review.

Prerrequisitos a respetar

• Las pasadas de grafo (relations, components) dependen de que los 6 módulos estén en phase: done.
• Relations precede a components.
• El vault legado (docs/vault-legacy/) no es fuente viva; no documentarlo como módulo activo.

Pitfall de granularidad

Validar con gv.py validate y actualizar el config (phase: done, last_sync_commit) deben ir en la misma subtarea. Si se separan, el checkpoint juez rechaza porque solo se cumple uno de los dos criterios (evidencia: rechazo iter-8 task/00).

Cobertura mínima por módulo

Cada módulo debe documentar, dentro de su stack, cuatro componentes clave para evitar rechazos en checkpoints [juez] de tasks 02-07:

1. Agent / Inicialización + Ciclo + Herramientas (si aplica): ficheros de entrada (__init__.py, main.py o equivalente), inicialización del servicio/agente, ciclo de ejecución si existe (bucles, endpoints, manejo de estado) y herramientas/funciones expuestas. Referencia: task/01.md línea 10 cita agent/agent.py, agent/__init__.py, agent/core/; task/02.md línea 10 exige documentación de agente + paquete core + rol de prompts. Fuente en bootstrap: secciones overview (entry points) y apis (interfaces públicas) de python.md línea 5-16.

2. Scripts / Entrada + Salida + Propósito: para cada script, documentar forma de invocación (CLI args, env vars si hay), salida esperada (stdout, ficheros generados) y propósito en una línea. Referencia: task/03.md línea 14 dice "solo intención, interfaz de invocación (entradas/salidas, propósito)". Las 14 utilidades de scripts/ deben aparecer nombradas (línea 37).

3. Tests / Fixtures + Coverage Goals: estructura de tests/ (qué fixtures existen, qué propósito tiene cada uno), cobertura declarada (qué módulo cubre cada fichero de test) y rol de runners/fixtures. Referencia: task/04.md línea 25 exige "mapear cada fichero de test al módulo/comportamiento que verifica"; línea 30 pide inventario de 14 ficheros (11 test_*.py + 2 runners + 1 fixture JSON).

4. Docs / Estructura + Términos Clave: para documentación o módulos sin runtime (e.g., docs/, stack generic), mapear contenido por tipo/ubicación (specs, ADRs, guidelines, colecciones Postman) y listar términos clave o secciones principales. Referencia: task/05.md línea 27 pide clasificación por tipo (specs, ADRs, planes, wiki, guidelines, artefactos); línea 36 exige mapeo a secciones del vault.

Cada sección generada debe terminar con bloque ## Evidence que cite rutas de fuente sin números de línea (bootstrap.md línea 27), y todo fichero debe llevar frontmatter con commit y last_sync (bootstrap.md línea 19; task/01.md línea 18). Falta de cualquiera de estos cuatro componentes causa rechazo determinístico en el checkpoint juez.

Cambios de capacidad: dónde colocarlos en el plan

Un cambio de capacidad (escribir .ralph/.env) no es una subtarea independiente. Debe ocurrir al inicio de la subtarea que lo necesita, como primer paso de esa misma subtarea.

Intercalar una subtarea cuyo único propósito sea cambiar .ralph/.env entre el checkpoint [juez] y las subtareas de documentación genera iteraciones vacías que no producen ningún artefacto. El agente gasta una iteración completa sin avanzar el vault.

Regla: si la subtarea [esfuerzo high] requiere capacidad alta, el cambio de .ralph/.env es la primera acción de esa subtarea, no una subtarea previa separada. Lo mismo aplica a cualquier transición de capacidad en cualquier subtarea.

Estructura de vault para módulos de suite de tests

Cuando el módulo a documentar es una suite de pruebas (no código de producción), la estructura de vault/repos/<módulo>/ difiere de los módulos de producción. En lugar de un único overview.md, se generan tres secciones especializadas:

• overview.md: estrategia de testing, capas (unitaria/integración/funcional), tooling y enfoque general.
• coverage.md: mapa fichero-por-fichero de qué módulo/comportamiento verifica cada test_*.py.
• runners-fixtures.md: rol de los runners de escenarios y los fixtures de datos.

Evidencia: task/04 (tests module), vault/repos/tests/README.md.

Estructura de vault para suites de tests

Los módulos de tipo test suite (como tests/) usan 3 secciones en lugar del número variable de secciones de módulos de producción:

1. overview.md — estrategia de test, capas, tooling.
2. coverage.md — mapa por fichero: qué módulo de producción verifica cada test file.
3. runners-fixtures.md — runners especiales (que requieren servicios externos como Ollama) y fixtures de datos.

No usar el patrón de secciones de módulos de producción (APIs, domain-model, etc.) para test suites: las abstracciones no encajan y producen secciones vacías.

Evidencia: tarea 04 (plan/task/04.md), iteración 11 del bucle (20260607).