albkhachikyan/task-splitter

Task Splitter — ejecución correcta más barata

Objetivo: completar la tarea principal con el menor costo total que aún cumpla con la calidad. Dos palancas: (1) enrutar cada pieza de trabajo al nivel más barato capaz, (2) pagar el contexto de inicio en frío de cada subagente una sola vez agrupando trabajo del mismo nivel en un solo hilo.

Lea references/routing-rubric.md antes de puntuar y references/batch-brief-template.md antes de escribir cualquier instrucción de lote.

Reglas estrictas

• El trabajo T0 nunca genera un agente. Los pasos deterministas (instalar, mkdir, mv, un valor de configuración, ejecutar un generador) se ejecutan en línea en el hilo principal. Un subagente de inicio en frío cuesta más que el comando.
• Nunca use subagent_type: "fork" para niveles baratos. Un fork siempre se ejecuta en el modelo padre e ignora model. Use general-purpose (o Explore para búsqueda de solo lectura) con un model y effort explícitos.
• Este skill autoriza explícitamente establecer effort en cada llamada de Agent que realiza, usando la tabla de niveles. Siempre pase tanto model como effort.
• Verificación mediante scripts, no modelos. Las pruebas, el lint, el typecheck y la compilación son ejecutados por el hilo principal. No gaste una llamada de modelo en revisar código que un script puede verificar.
• Escalar solo la subtarea que falla, un nivel, una vez. Después de una escalada, deténgase y pregunte al usuario.
• Nunca agrupe dos subtareas que editen el mismo archivo en diferentes lotes de la misma oleada.

Tabla de niveles (valores predeterminados — calibrar con el registro de enrutamiento)

Nivel	Puntuación	Se ejecuta como	Trabajo típico
T0	0	hilo principal, shell inline	instalar dependencias, crear directorios, renombrar, establecer valor de env/config
T1	1–3	model: haiku, effort: low	código boilerplate siguiendo un patrón existente, ediciones de copia, cableado CRUD simple, documentación, fixtures
T2	4–6	model: sonnet, effort: medium	código de funcionalidad normal, componentes, endpoints, pruebas siguiendo patrones existentes
T3	7–8	model: sonnet, effort: high	lógica multiarchivo, gestión de estado, integraciones, errores difíciles, autenticación/pagos/seguridad
T4	9–10	model: opus, effort: high	arquitectura, diseño transversal, modelo de datos, depuración difícil, rendimiento/concurrencia

Pesos de costo relativos para la vista previa: haiku = 1, sonnet = 3, opus = 5; multiplicador de esfuerzo low = 1, medium = 1.5, high = 2.5. T0 = ~0.

Flujo de trabajo

Fase 0 — Capturar y persistir

1. Reformule la tarea principal en ≤10 líneas: objetivo, restricciones, criterios de aceptación, pila, fuera del alcance.
2. Derive un slug. Busque un registro existente en <project>/.claude/task-splitter/ (ls .claude/task-splitter/ 2>/dev/null). Si coincide con esta tarea y tiene subtareas sin terminar → reanudar desde ella (saltar a la primera fase cuyo trabajo no esté hecho).
3. De lo contrario, cree <project>/.claude/task-splitter/<YYYY-MM-DD>-<slug>.md a partir de templates/split-ledger.md y complete la sección Context. Actualícelo después de cada fase. En modo plan, si no está permitido escribir archivos fuera del archivo del plan, coloque el contenido del registro dentro del archivo del plan bajo un encabezado ## Ledger y escriba el archivo real como el primer paso T0 después de la aprobación.

Fase 1 — Exploración ligera

Lea solo lo que necesita la división: manifiesto (package.json, pyproject, etc.), puntos de entrada, los archivos que toca la funcionalidad, utilidades existentes para reutilizar. Si se necesita una búsqueda amplia, use un agente Explore con model: haiku, effort: low y solicite solo rutas + hallazgos de una línea. Registre las utilidades reutilizables y las rutas de archivo exactas en el registro — se convierten en paquetes de contexto que evitan que los agentes baratos reexploren.

Fase 2 — Dividir

Divida el trabajo en subtareas atómicas. Cada subtarea tiene: id (S1, S2…), goal (una oración), files (rutas exactas, nuevas o existentes), depends_on (ids), done_check (un comando como pnpm test foo o un criterio preciso), type (etiqueta corta: install, scaffold, component, endpoint, test, migration, refactor, config, docs, debug, design…). Atómica = un agente puede terminarla sin decisiones que pertenezcan a otra subtarea. Extraiga las decisiones de diseño en su propia subtarea temprana (a menudo T4) para que las subtareas posteriores sean mecánicas y baratas.

Fase 3 — Puntuar y enrutar

Puntúe cada subtarea con la rúbrica de 5 dimensiones en references/routing-rubric.md (ambigüedad, profundidad de razonamiento, radio de impacto, contexto necesario, novedad; 0–2 cada una), aplique las reglas de anulación, luego asigne puntuación → nivel. Luego verifique ~/.claude/task-splitter/routing-log.md (si existe): si un type fue escalado en ≥2 de sus últimas 3 ejecuciones en un nivel, comience un nivel más arriba; si pasó a la primera ≥3 veces seguidas un nivel más abajo del que eligió, considere bajar un nivel.

Fase 4 — Agrupar en lotes

1. Construya oleadas de dependencias: oleada 1 = subtareas sin dependencias insatisfechas; oleada N = aquellas cuyas dependencias están todas en oleadas anteriores.
2. Dentro de cada oleada, agrupe por (model, effort), luego por área de código (misma carpeta de funcionalidad / módulo) para que un agente cargue archivos relacionados una sola vez.
3. Límites por lote: ≤6 subtareas o un área coherente; ningún archivo editado por dos lotes en la misma oleada (mueva la subtarea conflictiva al mismo lote o a la siguiente oleada).
4. Combine lotes pequeños: una subtarea T1 solitaria se une a otro lote T1 en la misma oleada si existe; una subtarea T1 solitaria que es casi mecánica puede hacerse inline en su lugar.
5. Las subtareas T0 se agrupan en un solo paso inline al comienzo de su oleada.

Fase 5 — Vista previa de costos (puerta de aprobación)

Escriba en el archivo del plan (o muéstrele al usuario, fuera del modo plan):

| Oleada | Lote | Modelo / esfuerzo | Subtareas | Costo estimado |
|--------|------|-------------------|-----------|----------------|
| 1      | inline| main / shell      | S1, S2    | ~0             |
| 1      | B1    | haiku / low       | S3, S4    | 2              |
| 1      | B2    | sonnet / medium   | S5        | 4.5            |
| 2      | B3    | opus / high       | S6        | 12.5           |
Total ≈ 19 unidades  (línea base todo-opus/high ≈ 75 unidades → ~75% más barato)

Costo estimado = número de subtareas × peso del modelo × multiplicador de esfuerzo. Incluya la línea base todo-opus/high para que se vea el ahorro. En modo plan, termine con ExitPlanMode; no ejecute antes de la aprobación.

Fase 6 — Ejecutar

Para cada oleada, en orden:

1. Ejecute el paso inline T0 de la oleada.
2. Lance todos los lotes de la oleada en UN mensaje (llamadas paralelas a Agent): Agent(subagent_type: "general-purpose", model: <modelo del nivel>, effort: <esfuerzo del nivel>, description: "<oleada>/<lote>: <corto>", prompt: <breve>). Construya cada instrucción a partir de references/batch-brief-template.md. El preámbulo compartido debe ser idéntico byte a byte en todos los lotes (compatible con caché de prompt) — coloque el contenido variable después.
3. Espere a que todos los lotes de la oleada informen antes de comenzar la siguiente oleada. Nunca escriba o adivine el resultado de un agente pendiente.
4. Actualice el registro con el estado de cada lote y los archivos reportados.

Fase 7 — Verificar y escalar

1. Después de cada oleada, el hilo principal ejecuta los comandos done_check de las subtareas más las comprobaciones globales baratas del proyecto (typecheck / lint / pruebas afectadas).
2. Una subtarea que falla se vuelve a ejecutar sola (o con otras fallas del mismo nuevo nivel) en un nivel más arriba, con la salida fallida y el informe del agente anterior adjuntos.
3. Máximo una escalada por subtarea. Si aún falla, deténgase y pregunte al usuario con un diagnóstico breve. Las fallas T4 van directamente al usuario.

Fase 8 — Registrar y aprender

1. Marque el registro como completo: nivel final por subtarea, pasó/escaló, archivos cambiados.
2. Agregue una línea por subtarea a ~/.claude/task-splitter/routing-log.md (cree la carpeta/archivo si falta; nunca dentro del repositorio git del skill): YYYY-MM-DD | <proyecto> | <type> | <nivel inicial> | <nivel final> | first-pass|escalated|failed
3. Informe al usuario en ≤10 líneas: qué se hizo, unidades de costo final vs línea base, cualquier escalada, cualquier cosa que quede abierta.

Convenciones de salida

• Mantenga el hilo principal ligero: los agentes devuelven informes cortos, no contenidos de archivos.
• Dé al usuario tablas, no prosa, para la división y la vista previa de costos.
• Si toda la tarea obtiene una puntuación ≤3 en total, o tiene ≤2 subtareas, dígalo y simplemente hágalo directamente — dividirla costaría más de lo que ahorra.