← Volver al listado de tecnologías ← Índice de Organic Driven Development (ODD)

Casos reales del repositorio

5 de noviembre de 2026 Por: Artiko

oddcasos-realesdocumento-de-featurebitacora

Casos reales del repositorio

Objetivos

Leer documentos de feature reales con criterio.
Reconocer cómo se registran evidencia, límites y decisiones.
Notar cómo cambió el propio formato con el tiempo.

El proyecto usa ODD sobre sí mismo y versiona sus documentos en odd/tasks/. Los fragmentos siguientes son citas del repositorio (licencia MIT). Se conserva su idioma y sus errores de tipeo, tal como exige la regla de citas textuales.

Caso 1: el formato actual en estado puro

Archivo: odd/tasks/odd-spec-by-reference.md. Porta a Gentle AI el contrato de traspaso por referencia que ya se había integrado en Gentle Shell.

El encabezado

# ODD spec-by-reference parity with gentle-pi (Gentleman-Programming/gentle-shell#1713)
Branch: `fix/odd-spec-by-reference` (base `origin/main` f4d3f3e8) · Delivery: single-pr · Runner: `go test ./internal/components/agentguidance/ ./internal/assets/`; full `go test ./...`
Engram mirror: `odd/odd-spec-by-reference/tasks` (project gentle-pi session) · Route: inline (user: no delegation today; RDD reviewers allowed)

En tres líneas aparece todo lo que exige el protocolo: objetivo, rama, estrategia de entrega y ejecutor. Además registra una instrucción del usuario sobre la ruta.

Especificaciones con cita

S1. Parity: "luego una vez que esto lo tengamos tenemos que hcer la paridad en gentle-ai" — the canonical ODD routing block carries the same contract gentle-pi merged in gentle-shell#1718.
S3. Change = only the affected spec and task: "A diferencia de SDD, un cambio no re hace todo, solo re hace esa spec y la tarea asociada".

Observa tres cosas: el artefacto está en inglés, las citas siguen en español, y el error “hcer” se conservó. Es el contrato de idioma en acción, junto con la regla de no reformular.

Tareas con evidencia

- [x] T1 (S2-S5) inline · canonical routing.go + routing_test.go + docs/usage.md · RED→GREEN · 6c664915
- [x] T2 (S6) inline · internal/assets/opencode/agents/gentle-ai-{worker,verify,explore}.md + assets test · RED→GREEN · 122e85b7
- [x] T4 (S5) inline · review follow-ups: guard verify examples in the canon (authorized, isolated state) and pin docs/usage.md to the contract · RED→GREEN · 5c460fce
- [ ] T3 (S1) pending merge · in gentle-pi, `npm run mirror:odd-routing` to regenerate `fixtures/odd-routing-canonical.md`

La tarea T3 queda sin marcar, con su condición, aunque está antes en la numeración que T4. Las tareas conservan su ID estable cuando aparecen otras.

La bitácora

L1 2026-10-03 user (verbatim): > luego una vez que esto lo tengamos tenemos que hcer la paridad en gentle-ai
L4 2026-10-03 T1 evidence (risk: medium, canonical prompt contract for every agent):
   RED: TestRenderRoutingOrganicTaskContinuity failed for all 17 catalog agents on the new spec-by-reference clauses.
   GREEN: `go test ./internal/components/agentguidance/ ./internal/assets/` ok; `go test ./...` 80 packages ok; `go vet` and `gofmt -l` clean.
L6 2026-10-03 next: push + PR to Gentleman-Programming/gentle-ai need user authorization; then T3 in gentle-pi.

La evidencia nombra la prueba fallida. No dice solo “RED ok”.
L6 separa la implementación de la entrega: push y PR requieren autorización.
Otra entrada registra que una revisión RDD encontró dos hallazgos, y estos se convirtieron en las tareas T4 y T5. Los hallazgos entraron como trabajo porque la revisión fue autorizada, y queda constancia de ello.

Lectura del caso

flowchart LR
    A["Pedido: hacer la paridad"] --> B["S1 a S6"]
    B --> C["T1 y T2 inline"]
    C --> D["Revisión RDD autorizada"]
    D --> E["Hallazgos"]
    E --> F["T4 y T5"]
    F --> G["T3 pendiente de merge"]

Caso 2: registrar lo que no se hizo

Archivo: odd/tasks/task-size-canon.md. Lleva a todos los agentes las reglas de tamaño de tarea.

S5. Agent escalation: "que el agente defina segun nuestros criterios que es algo que amerite una verificacion o un RDD". `gentle-ai review assess --escalate-item <1-6> --escalate-reason <text>` raises passive or medium to high and records an `agent_escalation` reason; it never lowers a tier.

La parte más instructiva está en la evidencia:

L3 2026-10-03 G2 evidence (risk: HIGH, CLI flag contract; independent verifier not run, user forbade delegation): RED `flag provided but not defined: -escalate-item`; GREEN all `TestReviewAssess*` incl. the published-schema check [...]. Limit: START still selects lenses from the native tier; the escalation makes the review due at this commit (`high_risk`), it does not change the lens count.

Hay tres elementos que este registro hace visibles:

Elemento	Qué muestra
”independent verifier not run, user forbade delegation”	Un punto de alto riesgo activaría un verificador, pero la orden del usuario lo impidió, y queda escrito
El texto exacto del RED	`flag provided but not defined: -escalate-item` es una falla observada, no una afirmación
”Limit:“	Declara hasta dónde llega el cambio

También registra trabajo diferido con su destino:

- [ ] G3 (S4) deterministic lowering accuracy · filed as gentle-ai#5216

Caso 3: una decisión que se va acotando

Archivo: odd/tasks/verify-always-rdd-high.md. Empezó como un cambio de reglas de verificación y revisión.

Este documento muestra el valor de la bitácora para decisiones que evolucionan. Una lectura ordenada:

Entrada	Qué pasó
L1	Pedido original: “creo que tenemos que cambiar una regla”
L5	El usuario frena: “Pero te lo dije para que lo pensemos juntos”. Se pausa la implementación
L7	Sobre `slice_budget_reached`: “Hablemos sobre esto”
L9	Aclara qué quiso decir con las lentes: según lo que se toca, no según la gravedad
L12	Acota: “Hagamos algo, solo cambia lo del análisis según el riesgo la llamada de la lente”
L18	Se reanuda el resto con un plan aprobado

Y la sección de tareas refleja el acotamiento:

Scope narrowed by L12: only agent-driven lens selection ships now. S1 (verify always by tier) and S2 (RDD only on high) are paused, not implemented.

Qué muestra este caso

Decisiones textuales. Las opciones aprobadas se citan junto con su descripción:

S10 [...] Approved question (verbatim): "¿Cómo lo entregamos?" User selected (verbatim): "Un PR por repo".

La autorización. En L5 la implementación se pausa porque el usuario lo planteó para pensarlo en conjunto. Se deduce que una reflexión se había tomado como encargo. Es exactamente el caso del paso Authorize, ocurrido en el proyecto que define esa regla.

Trabajo que sigue abierto. La tarea B1, que rechazaría un START sin lentes, sigue sin marcar y depende de otros lanzamientos. Si solo leyeras las especificaciones, creerías que ya funciona así: por eso importan las casillas.

La evolución de un valor. C2 explica por qué slice_budget_reached sigue en el código sin devolverse:

L20 C2: RED (assess medium>=400 was review_due slice_budget_reached; Stop hook reminded on a medium candidate), then GREEN: reviewAssessDue reports medium as under_budget (no new enum value, so Gentle Shell decoders keep working; slice_budget_reached kept in the schema enum only for earlier results) [...]

No se agregó un valor nuevo para no romper a los consumidores, y el anterior quedó en el esquema solo por resultados previos. Ese detalle resuelve la contradicción que señala el capítulo 16.

Caso 4: honestidad en una entrega grande

Archivo: odd/tasks/remove-sdd-odd-only-main.md. El retiro de SDD: la entrega más grande de estos ejemplos, con una instantánea de 860 rutas en staging.

No sigue el formato actual de ## Specs, porque es anterior al traspaso por referencia. Vale la pena leerlo por cómo declara sus límites:

- Not available/unauthorized: native Windows run, external-agent journeys, driven bench, v3.7 packed download. Native RDD review declined by user for this candidate; no receipt; delivery under ordinary repository policy with PR CI as full-suite proof.

Subsequent authorized unstaged work changed the candidate; these historical checks do not certify the final bytes.

Estas dos citas ilustran varias reglas juntas:

Lo no disponible se enumera.
Declinar una revisión queda registrado: no receipt, sin fingir una aprobación.
Una comprobación certifica solo los bytes que comprobó.
La prueba de la suite completa se delegó a la CI del PR por decisión del usuario, y se dice así.

Además registra un error corregido: se había intentado agregar la limpieza con la tecla de retroceso en un selector independiente, y “an unjustified attempt […] was reverted”.

Evolución del formato

Al leer odd/tasks/ por orden cronológico se nota que el formato cambió. Los documentos más antiguos usan secciones como ## Objective, ## Scope y ## Acceptance criteria. Los más nuevos usan el orden fijo actual.

flowchart LR
    subgraph A["Antes"]
        A1["Objective"] --> A2["Problem"] --> A3["Scope"] --> A4["Tasks"] --> A5["Acceptance criteria"] --> A6["Progress"]
    end
    subgraph B["Formato actual"]
        B1["Encabezado corto"] --> B2["## Specs"] --> B3["## Tasks"] --> B4["## Log"]
    end
    A --> B

La especificación por referencia motivó el cambio: el texto anterior prescribía “objective, problem, why, scope, constraints…” y pasar “the locator and relevant context”, y el nuevo fija citas textuales y un orden estable. Usa los documentos recientes como plantilla.

Plantilla derivada de los casos

# <objetivo en una línea>
Branch: `<rama>` · Delivery: <estrategia> · Runner: `<comando>`
Engram mirror: `odd/<feature>/tasks` · Route: <inline o motivo>

## Specs
S1. <requisito>: "<cita textual>". Aceptación: <criterio observable>.
S2. Assumption: <supuesto marcado como tal>.

## Tasks
- [x] T1 (S1) inline · <superficie> · RED→GREEN · <commit>
- [ ] T2 (S2) <estado> · <condición>

## Log
L1 <fecha> user (verbatim): > <pedido original>
L2 <fecha> T1 evidence (risk: <nivel o punto>): RED: <falla exacta>. GREEN: <comando y resultado>.
L3 <fecha> next: <siguiente paso y autorización requerida>.

Actividad

Abre en el repositorio un documento de odd/tasks/ a tu elección. Responde:

¿Puedes retomar el trabajo solo con ese documento?
¿Qué evidencia es observada y cuál es una afirmación sin prueba?
¿Qué quedó sin hacer, y se dice por qué?
¿Qué harías distinto en tu propio proyecto?

Autoevaluación

¿Por qué los documentos conservan errores de tipeo en las citas?
- A. Por descuido de los agentes
- B. Porque las citas son textuales y no se reformulan
- C. Para diferenciar autores
- D. Por una limitación de Engram
En task-size-canon.md no corrió el verificador pese al riesgo alto. ¿Cómo se trató?
- A. Se ocultó en la bitácora
- B. Se marcó como verificado
- C. Se canceló la tarea
- D. Se registró que no corrió y por qué
¿Qué enseña la entrada L5 de verify-always-rdd-high.md?
- A. Una reflexión no autoriza implementar
- B. El agente debe preguntar más
- C. Las especificaciones no cambian
- D. RDD debe estar siempre activo
Una comprobación pasó, y luego cambió el código. ¿Qué afirma remove-sdd-odd-only-main.md?
- A. Sigue siendo válida
- B. Se debe borrar del documento
- C. Es histórica, y no certifica los bytes finales
- D. Equivale a una aprobación

Respuestas

B. Las especificaciones citan textualmente y nunca resumen.
D. La bitácora dice “independent verifier not run, user forbade delegation”.
A. El usuario aclara que lo dijo para pensarlo juntos, y la implementación se pausa.
C. “These historical checks do not certify the final bytes.”

Lista de control

Leí al menos un documento real completo.
Entiendo cómo se registran evidencia y límites.
Distingo una casilla sin marcar de una especificación cumplida.
Tengo una plantilla para mi primer documento.

Fuentes

odd/tasks/odd-spec-by-reference.md, odd/tasks/task-size-canon.md, odd/tasks/verify-always-rdd-high.md, odd/tasks/remove-sdd-odd-only-main.md, odd/tasks/odd-mandatory-delegation.md.