capability-escalation

name	capability-escalation
description	Patrón de escalado de capacidad del modelo por subtarea — cuándo cambiar RALPH_MODEL_CAPABILITY en .ralph/.env
metadata	{"tipo":"metodologia"}

Cada tarea del plan sigue el ciclo: low → med → high → volver a med:

1. low — subtarea inicial de validación de contexto (ligera, no genera contenido).
2. med — trabajo sustantivo de inventario y preparación.
3. high — generación de documentación (secciones vault) y checkpoints juez.
4. Vuelta a med — tras pasar el último checkpoint juez de la tarea.

El cambio se aplica modificando la línea RALPH_MODEL_CAPABILITY=... en .ralph/.env. Cada subtarea de cambio de capacidad está marcada con [esfuerzo low/med/high] en los ficheros plan/task/*.md.

Este patrón está implementado en task/00.md–05.md y funciona correctamente (evidencia: iters 1–9 de task/00 donde iters 4–7 usaron opus y el resto sonnet).

Pitfall — haiku en subtareas de interpretación de plan

El modelo low (haiku) no debe usarse en subtareas que requieran interpretar el plan para decidir qué ejecutar. En iteración 12 de la sesión 20260606, haiku consumió una iteración completa deliberando sobre qué subtarea era "futura" vs "actual" sin marcar ningún [x] ni producir output. La iteración se perdió.

Síntoma observable: la sección ---- claude output ---- del log contiene razonamiento pero ningún [x] nuevo en ningún plan/task/*.md.

Regla: low solo se asigna a subtareas puramente mecánicas y autocontenidas (p. ej. leer un fichero de contexto, confirmar que algo existe). Nunca a subtareas que requieran leer el plan y decidir el siguiente paso. Si se produce el síntoma, escalar a med para esa subtarea.

Pitfall — esfuerzo intermedio entre juez y documentación multiplica iteraciones de bookkeeping

Síntoma observable: insertar un [esfuerzo med] (o similar) entre un checkpoint [juez] y las subtareas de documentación sustantiva provoca que sonnet escale a high para el juez, opus ejecute el juez, y luego sonnet consuma una iteración entera solo para bajar de vuelta a med antes de la documentación — sin producir ningún artefacto de valor.

Cómo evitarlo: agrupar todos los cambios de capacidad consecutivos en la misma iteración si son puramente mecánicos (un write de una línea a .ralph/.env), o situar el escalado med→high solo una vez antes del bloque juez+documentación cuando ambos requieren capacidad alta.

Evidencia: en task/04 (session 20260607), iteraciones 9-10 consumidas únicamente por bookkeeping high→med tras el primer checkpoint juez; iteración 13 consumida únicamente por med→high antes de gv.py validate. 4 de 11 iteraciones de la tarea tocaron solo .ralph/.env.