Paso 5: El documento de feature

Objetivos

• Escribir un documento de feature con la estructura y el orden exactos.
• Citar requisitos sin parafrasear ni agregar nada.
• Traspasar trabajo por referencia.
• Aplicar un cambio de requisitos reabriendo solo lo afectado.

---

Cuándo y cómo se crea

Para una tarea grande autorizada, el agente crea el documento y su espejo antes de la primera escritura de código, sin pedir permiso para las tareas ni para el almacenamiento. Te avisa en una línea qué documento creó y cuántas tareas contiene.

Elemento	Valor
Archivo	odd/tasks/<feature-name>.md
Espejo	Tema de Engram odd/<feature-name>/tasks, en el ámbito del proyecto
Nombre	Descriptivo y seguro para nombres de archivo. No se sobrescribe otra feature
Cantidad	Un solo documento, sin archivo de plan ni tema aparte

---

La estructura

El orden es fijo por un motivo declarado: el contenido estable va primero y la bitácora creciente al final.

flowchart TD
    A["Encabezado de 2 o 3 líneas<br/>objetivo, rama, estrategia de entrega, ejecutor de pruebas"] --> B["## Specs<br/>S1..Sn con citas textuales,<br/>criterios y comprobaciones"]
    B --> C["## Tasks<br/>una línea por tarea: ID, S#, ruta, estado, commit"]
    C --> D["## Log<br/>L1 es el pedido textual,<br/>luego correcciones y evidencia"]

Un ejemplo completo

Este ejemplo es ilustrativo y sigue el formato de los documentos reales del repositorio:

# Exportación CSV de reportes
Rama: `feat/csv-export` · Entrega: ask-on-risk · Ejecutor: `bun test src/reports`
Objetivo: exportar el reporte respetando los filtros activos.

## Specs
S1. Exportar a CSV: "Agrega exportación CSV con los filtros actuales del reporte."
    Aceptación: el archivo contiene solo las filas del filtro activo.
S2. Mensaje al no haber datos, exacto: "No hay datos para exportar".
    Aceptación: se muestra ese texto y no se descarga ningún archivo.
S3. Supuesto (marcado como tal): el separador es coma.

## Tasks
- [x] T1 (S1) inline · ruta y serializador · RED→GREEN · a1b2c3d
- [ ] T2 (S2) inline · mensaje vacío · pendiente

## Log
L1 2026-11-06 usuario (textual): > Agrega exportación CSV con los filtros actuales del reporte.
L2 2026-11-06 usuario (textual): > si no hay datos que diga "No hay datos para exportar"
L3 2026-11-06 T1 evidencia: RED `reports.csv filtra por estado` falló, GREEN tras el cambio.
L4 siguiente paso: T2.

Por el contrato de idioma, un agente generaría este documento en inglés por defecto y conservaría las citas en tu idioma. El capítulo 18 explica esa regla. Aquí se muestra en español para facilitar la lectura.

## Specs: la parte más delicada

Las especificaciones se numeran S1, S2 y así sucesivamente, y contienen el alcance autorizado, los criterios de aceptación y las comprobaciones aplicables. Las reglas son exigentes:

• Las frases exactas, mensajes de error, comandos y ejemplos del usuario se citan textualmente y en su idioma.
• Se pueden numerar y ordenar esos fragmentos, pero nunca resumirlos ni reformularlos.
• No se agregan requisitos que nadie pidió.
• Los supuestos se marcan como supuestos.

Si tu pedido contiene un error de tipeo o una frase informal, se conserva. En el documento real de task-size-canon.md, la especificación cita “que el agente defina segun nuestros criterios”, sin acento, tal como se dijo.

## Tasks: una línea por tarea

Cada tarea lleva un ID estable, sus S# vinculadas, la ruta, el estado y la identidad del commit o la evidencia RED/GREEN.

- [x] T1 (S2-S5) inline · routing.go + tests + docs · RED→GREEN · 6c664915
- [ ] T3 (S1) pendiente de merge · regenerar el fixture en gentle-pi

La ruta registrada cumple otra función: el Route declaration exige anotar por tarea si fue inline o delegada, junto con la evidencia del disparador, para que una delegación omitida resulte observable.

## Log: la bitácora

• L1 es tu pedido original, textual.
• Tus correcciones posteriores se agregan textuales y con fecha.
• También se agregan análisis del problema, razones de los cambios aceptados, evidencia, progreso y siguiente paso.
• Las correcciones rutinarias van breves. La fuente aclara que no es un diario exhaustivo de decisiones.

---

Traspaso por referencia

Esta es la práctica que da sentido al formato. Un traspaso no resume el pedido: apunta al documento.

Spec: odd/tasks/csv-export.md, T2, S2

sequenceDiagram
    participant P as Parent
    participant W as Worker
    participant V as Verificador
    participant D as Documento
    P->>W: Spec odd/tasks/csv-export.md, T2, S2
    W->>D: Leer desde el inicio hasta ## Log
    W->>P: Cambios, comprobaciones y S# cubiertas
    P->>V: Documento completo, commit base y sondas
    V->>D: Leer todo, incluido ## Log
    V->>P: Veredicto por cada S#

Actor	Qué recibe	Qué lee	Qué devuelve
Worker	Localizador, tarea y S#	Hasta ## Log	Las S# cubiertas y las que no pudo cumplir
Explorador	Localizador cuando existe	Hasta ## Log	Mapa con evidencia
Verificador	Documento completo, nunca una sola tarea	Todo, incluidas las entradas textuales de ## Log	Veredicto por S#

¿Por qué el worker se detiene antes de ## Log? La estructura pone el contenido estable primero, y el worker no necesita el historial para implementar. El verificador en cambio lo lee entero, porque comprueba el pedido textual.

Si no hay documento, porque la tarea es pequeña y aun así se delega algo, el traspaso incluye el pedido textual.

---

Cuando cambia un requisito

Aquí aparece la diferencia que el mantenedor destacó respecto de SDD:

flowchart LR
    A["Corrección del usuario"] --> B["Agregar entrada textual en ## Log"]
    B --> C["Reescribir solo la S# afectada"]
    C --> D["Reabrir solo la tarea vinculada"]
    D --> E["Conservar todo lo demás"]

Reglas complementarias:

• Se conserva el trabajo completado válido y el que no tiene relación.
• Se agregan tareas realmente nuevas o se reabren las invalidadas, con un motivo.
• Se revisan sus comprobaciones.
• Un cambio de alcance de negocio sigue requiriendo tu autorización.
• Los hallazgos por sí solos no autorizan ampliar el alcance.

Las casillas no son aprobaciones

Una casilla marcada significa que se observó un resultado con su prueba aplicable. No equivale a una aprobación ni a un recibo de revisión. Las comprobaciones fallidas, no disponibles, omitidas o pendientes se registran con honestidad.

---

Qué documento no se crea

El título de la práctica es “un documento”. La fuente prohíbe explícitamente los archivos de plan separados y los temas aparte en Engram. Además, para trabajo pequeño o de solo lectura no se crea ningún documento: el diff es suficiente.

---

Actividad

Redacta el documento de feature de tu pedido grande del capítulo 1:

1. Escribe L1 con el pedido tal como lo dijiste.
2. Extrae las S# usando citas textuales, sin mejorar la redacción.
3. Marca como supuesto todo lo que agregaste.
4. Escribe las tareas en una línea cada una, con su ruta.
5. Escribe el traspaso de la primera tarea en una sola línea.

Luego compáralo con los ejemplos reales del capítulo 20.

---

Autoevaluación

1. ¿Qué contiene L1?

   • A. Un resumen del objetivo
   • B. El plan inicial del agente
   • C. La evidencia de la primera tarea
   • D. El pedido original del usuario, textual

2. ¿Hasta dónde lee el documento un worker?

   • A. Hasta ## Log
   • B. Solo la línea de su tarea
   • C. Todo, incluida la bitácora
   • D. Únicamente el encabezado

3. Cambia un requisito. ¿Qué se hace?

   • A. Regenerar todas las especificaciones y tareas
   • B. Crear un segundo documento de feature
   • C. Registrar en ## Log, reescribir la S# afectada y reabrir su tarea
   • D. Cerrar la feature y empezar otra

4. ¿Qué hace el documento con un requisito que el agente considera conveniente pero nadie pidió?

   • A. Lo agrega como S# normal
   • B. No lo agrega: solo puede aparecer un supuesto marcado como tal
   • C. Lo agrega al final de ## Tasks
   • D. Lo implementa y lo registra después

Respuestas

1. D. Es la regla literal de la bitácora.
2. A. El verificador sí lee todo.
3. C. Es la práctica que la fuente contrapone a regenerar todos los artefactos.
4. B. “Do not add requirements the user never asked for, and mark assumptions as assumptions.”

Lista de control

• Sé el orden de las secciones y por qué es fijo.
• Cito sin reformular, incluso cuando el original tiene errores.
• Mis traspasos son referencias de una línea.
• Reabro solo lo afectado ante un cambio de requisitos.

Fuentes

internal/components/agentguidance/routing.go, docs/usage.md, odd/tasks/odd-spec-by-reference.md, odd/tasks/task-size-canon.md, internal/assets/opencode/agents/gentle-ai-worker.md, internal/assets/opencode/agents/gentle-ai-verify.md, internal/assets/opencode/agents/gentle-ai-explore.md.