Commits por unidad de trabajo y estrategias de entrega

Objetivos

• Cortar commits que representen una unidad de trabajo.
• Elegir una estrategia de entrega para una feature.
• Aplicar las reglas de un PR encadenado.
• Separar lo que el agente hace por sí solo de lo que te corresponde decidir.

---

Quién decide cada cosa

flowchart LR
    A["Implementación grande autorizada"] --> B["Commits por unidad<br/>en la rama de la feature"]
    B --> C{"Decisión del usuario"}
    C --> D["Push"]
    D --> E["Pull request"]
    E --> F["Merge"]

Si estás en la rama por defecto, primero se crea una rama. Una tarea pequeña no hace commits, salvo que lo pidas.

---

Qué es una unidad de trabajo

El skill work-unit-commits define la regla base: un commit representa un comportamiento entregable, un arreglo, una migración o una unidad de documentación.

Regla	Requisito
Por unidad de trabajo	Cada commit representa algo entregable
No por tipo de archivo	Evitar models, luego services, luego tests si ninguno funciona solo
Pruebas con el código	Las pruebas van en el commit del comportamiento que verifican
Documentación con el cambio	Junto a la funcionalidad o flujo que explica
Contar una historia	El diff y el mensaje explican por qué existe el commit
Listo para un PR futuro	Cada commit podría convertirse en un PR encadenado
El presupuesto no es golf de código	Nunca achicar un diff borrando comentarios, líneas, docs o pruebas

Cortes débiles y cortes por unidad

Corte débil	Corte por unidad de trabajo
add models	feat(auth): add token validation domain model and tests
add services	feat(auth): wire token validation into login flow
add tests	Las pruebas se incluyen con cada comportamiento
update docs	La documentación se incluye con el cambio que explica

Lista antes del commit

• El commit tiene un propósito claro.
• El repositorio sigue teniendo sentido aplicando solo este commit.
• Incluye pruebas o documentación cuando corresponde.
• Se puede revertir sin deshacer trabajo ajeno.
• El comando de prueba enfocada y su resultado exacto quedan registrados.
• El escenario de ejecución queda registrado, o un N/A explícito explica por qué no hay frontera de ejecución.
• La frontera de reversión nombra los archivos o comportamientos exactos.
• El mensaje explica el resultado, no la lista de archivos.

---

El ritmo en ODD

El protocolo no pide un commit por tarea. Pide porciones revisables de unas 400 líneas de autoría, con estas reglas:

• Mensaje en formato de Conventional Commit.
• Pruebas y documentación junto al comportamiento.
• Una unidad cuya línea Risk nombra un punto de alto riesgo va en su propio commit, para que se pueda revisar sola.
• La última porción cierra la feature.
• El documento de feature registra qué commit contiene cada tarea, como evidencia.

gitGraph
    commit id: "base"
    branch feat/csv-export
    checkout feat/csv-export
    commit id: "T1 y T2, ~350 líneas"
    commit id: "T3, Risk item 3, solo"
    commit id: "T4 y docs, cierra"

Contar líneas

Las líneas de autoría son adiciones más eliminaciones, sin archivos generados. El parent lleva un conteo acumulado a partir de los commits. Al crear el documento también hace un pronóstico desde la lista de tareas.

Conviene recordar la distinción del capítulo 6: la heurística por tarea no detiene nada, mientras que el presupuesto de entrega lee la rama acumulada y activa una estrategia.

---

Las estrategias de entrega

Se elige una por feature. Está documentada en CONTRIBUTING.md y en el texto canónico.

Estrategia	Cuándo se usa	Qué ocurre en el límite
ask-on-risk	Por defecto	Pregunta una vez por la estrategia de cadena
auto-chain	El cambio debe revisarse en porciones	Pregunta solo si falta la estrategia de cadena, y divide automáticamente
single-pr	El cambio debe aterrizar de forma atómica	Un PR que supere el presupuesto requiere aprobación de size:exception
exception-ok	Un mantenedor ya aprobó un PR grande	Se registra la excepción, sin que eso sea permiso para abrir el PR

flowchart TD
    A["Crear documento de feature"] --> B["Pronóstico de líneas"]
    B --> E{"¿Pronóstico o conteo superan ~400?"}
    C["Commit de una unidad"] --> D["Conteo acumulado"]
    D --> E
    E -->|"No"| C
    E -->|"Sí"| F["Aplicar la estrategia<br/>antes del siguiente commit"]
    F --> G["Registrar en el documento<br/>qué commits contiene cada PR"]
    G --> C

La comprobación ocurre desde el principio: si el pronóstico ya supera el presupuesto al crear el documento, la estrategia se aplica antes del primer commit. Ambas elecciones se guardan, para no repetir la pregunta.

Los skills work-unit-commits y chained-pr se resuelven por nombre en el registro antes de planificar o crear un PR. Sus rutas no se escriben a mano.

---

Las estrategias de cadena

	Stacked PRs to main	Feature Branch Chain
Identificador	stacked-to-main	feature-branch-chain
Conviene cuando	Cada porción puede integrarse de forma independiente	La funcionalidad debe integrarse completa antes de llegar a main
Rama de destino	Hacia main	Una rama rastreadora con un PR en borrador que no se integra

En una Feature Branch Chain, el PR rastreador se abre como borrador. El primer hijo apunta a la rama rastreadora, y los siguientes a su padre inmediato.

flowchart TD
    subgraph S["stacked-to-main"]
        M1["main"] --- P1["PR 1"] --- P2["PR 2"] --- P3["PR 3"]
    end
    subgraph F["feature-branch-chain"]
        M2["main"] --- T["Rastreador en borrador"] --- H1["Hijo 1"] --- H2["Hijo 2"]
    end

Reglas estrictas de chained-pr

• Se dividen los PR de más de 400 líneas cambiadas, salvo que un mantenedor acepte size:exception.
• Cada PR debe poder revisarse en unos 60 minutos.
• El presupuesto condiciona cómo se corta, nunca el código.
• Una sola pasada honesta de corte. Si ninguna división cohesiva encaja, se deja de iterar, se conserva la mejor, y se informa el total con una recomendación de size:exception.
• Cada PR indica inicio, fin, dependencias, trabajo posterior y lo que queda fuera.
• Cada PR hijo incluye un diagrama de dependencias que marca el actual con 📍.
• Un diff contaminado se considera un error de base, y se reubica o rebasa hasta que solo aparezca la unidad actual.
• No se mezclan estrategias de cadena después de elegir una.

La metáfora del proyecto

Los commits por unidad de trabajo son los ladrillos; los PR encadenados son los tramos del muro. No hagas que los revisores inspeccionen el edificio entero de una sentada.

CONTRIBUTING.md (traducción propia)

Lista de decisión

Antes de abrir el PR, según CONTRIBUTING.md:

• ¿Un revisor puede entenderlo en unos 60 minutos?
• ¿Tiene 400 líneas cambiadas o menos?
• ¿Cada commit incluye su código, pruebas y documentación?

Si alguna respuesta es no, corresponde auto-chain o una aprobación explícita de size:exception.

---

Relación con la revisión nativa

Cuando RDD está activo, cada commit por unidad se evalúa. Lo detalla el capítulo 16. Dos ideas se anticipan aquí:

• El candidato de revisión es un commit por unidad o una porción de PR. Nunca una casilla de tareas ni la rama acumulada completa.
• El límite revisado avanza: el punto de partida es la bifurcación de la rama, y cada límite revisado se convierte en la siguiente base.

---

Una advertencia del propio mantenedor

Entre los errores que relata en la crónica de RDD está este: agregó al staging un archivo sin leer su diff, mientras un agente escribía en él. Incluyó 154 líneas de trabajo ajeno sin terminar e hizo push de una rama que no compilaba. Su comentario: ningún guardia lo protege de un git add apresurado.

De ahí la utilidad de revisar git diff --stat y git diff --cached --stat antes de cada commit, tal como recomienda el skill.

---

Actividad

Toma el historial de una rama reciente tuya y reorganízalo sobre el papel:

1. Agrupa los commits por unidad de trabajo.
2. Marca cualquier unidad con un punto de alto riesgo y sepárala.
3. Cuenta las líneas de autoría de cada porción.
4. Elige una estrategia de entrega y una de cadena, justificando en una línea cada una.

---

Autoevaluación

1. ¿Qué lleva su propio commit?

   • A. Cada archivo de pruebas
   • B. Cada tarea del documento
   • C. Cada 100 líneas
   • D. Una unidad cuya línea Risk nombra un punto de alto riesgo

2. ¿Cuál es la estrategia por defecto?

   • A. ask-on-risk
   • B. auto-chain
   • C. single-pr
   • D. exception-ok

3. Hiciste una pasada de corte y un PR sigue en 620 líneas sin una división cohesiva. ¿Qué se hace?

   • A. Comprimir código hasta llegar a 400
   • B. Eliminar las pruebas a otro PR
   • C. Conservar la mejor división y recomendar size:exception
   • D. Repetir el corte hasta que encaje

4. Cada porción puede integrarse por separado en main. ¿Qué cadena encaja?

   • A. feature-branch-chain
   • B. stacked-to-main
   • C. exception-ok
   • D. Ninguna: se debe usar single-pr

Respuestas

1. D. Así se puede revisar por separado.
2. A. Es la marcada como predeterminada en el protocolo y en CONTRIBUTING.md.
3. C. El corte es de una pasada, y el presupuesto nunca altera el código.
4. B. La otra se recomienda cuando hay que integrar antes de llegar a main.

Lista de control

• Mis commits representan unidades, no capas ni tipos de archivo.
• Separo las unidades de alto riesgo.
• Sé elegir entre las cuatro estrategias y las dos cadenas.
• Hago una sola pasada de corte.
• Reviso el diff del staging antes de cada commit.

Fuentes

internal/assets/skills/work-unit-commits/SKILL.md, internal/assets/skills/chained-pr/SKILL.md, internal/assets/skills/chained-pr/references/chaining-details.md, CONTRIBUTING.md, internal/components/agentguidance/routing.go, docs/architecture/the-organic-rdd-story.md.