Paso 1: Autorizar
Objetivos
- Clasificar un pedido como lectura, cambio o ambiguo.
- Enumerar lo que prohíbe el modo de solo lectura.
- Distinguir entre autorizar un cambio y autorizar su entrega.
La regla
El primer paso establece si el resultado pedido autoriza explícitamente un cambio.
Investigation, explanation, review, audit, comparison, and solution-proposal or planning-only requests are read-only unless the user explicitly requests implementation or another mutation.
internal/components/agentguidance/routing.go
La regla por defecto es conservadora. Si pides una revisión, el agente revisa. Encontrar errores durante esa revisión no lo habilita para corregirlos.
flowchart TD
A["Pedido"] --> B{"¿Pide explícitamente<br/>implementar o mutar?"}
B -->|"Sí"| C["Autorizado<br/>sigue al paso 2"]
B -->|"No: investigar, explicar, revisar,<br/>auditar, comparar, proponer, planificar"| D["Solo lectura"]
B -->|"Ambiguo o condicional"| E["Una aclaración"]
E --> F["Sigue en solo lectura<br/>hasta tener respuesta"]
F --> BQué permite y qué prohíbe la solo lectura
| Permitido | Prohibido |
|---|---|
| Inspeccionar | Escribir o editar archivos |
| Explicar | Delegar a un writer |
| Comparar | Invocar un apply |
| Recomendar | Crear artefactos de implementación |
Un plan o una propuesta pedidos también caen aquí. “Propón cómo migrarías esto” produce una propuesta en la conversación. No crea el documento de feature ni archivos de plan, porque todavía no hay autorización para implementar.
Ejemplos
| Pedido | Clasificación | Motivo |
|---|---|---|
| ”¿Por qué falla este test?” | Solo lectura | Investigación |
| ”Revisa este módulo y dime qué mejorarías” | Solo lectura | Revisión con recomendación |
| ”Compara estas dos librerías” | Solo lectura | Comparación |
| ”Haz que este test pase” | Autorizado | Pide un resultado que exige cambiar algo |
| ”Agrega exportación CSV con los filtros actuales” | Autorizado | Ejemplo de la propia guía de inicio |
| ”Si crees que vale la pena, corrígelo” | Ambiguo y condicional | Deja la decisión abierta |
| ”Esto debería validar emails” | Ambiguo | Puede ser observación o encargo |
Los dos últimos ilustran la aclaración única: el agente pregunta una vez y espera. Hacer varias preguntas seguidas o avanzar mientras tanto no forma parte del protocolo.
Ojo con las señales de pausa
Hay un caso que parece ambiguo y no lo es. El texto de Pi lo plantea directamente en este paso y el canónico lo repite al cerrar: si dices que quizá detengas al agente o que retomarás luego, estás pidiendo notas y commits separados. No estás ordenando que se detenga.
Las respuestas cortas
La sección de identidad del orquestador define cómo se interpretan “sí”, “dale” o “eso mismo”: se leen contra la propuesta inmediatamente anterior.
- Si aceptas sin ambigüedad una acción concreta que ya comprendes, el agente la ejecuta sin volver a preguntar, dentro del alcance acordado.
- Confirmar una preferencia no autoriza implementar.
- Si la intención de cambio sigue sin estar clara, corresponde una pregunta enfocada.
Hay un límite importante:
Contextual approval never substitutes for provider-owned consent, exact-token authorization, or separate publishing and destructive-action permission.
internal/assets/skills/_shared/odd-orchestrator-sections.md
En otras palabras, un “dale” a una propuesta de código no equivale a consentir una revisión nativa, publicar un paquete ni borrar datos.
Autorizar un cambio no autoriza entregarlo
Una autorización de implementación cubre los pasos necesarios dentro del alcance: código, documentación y verificación. Lo que no cubre se representa bien en una tabla:
| Acción | ¿La cubre “implementa X”? |
|---|---|
| Editar el código y las pruebas | Sí |
| Actualizar la documentación afectada | Sí |
| Ejecutar las comprobaciones aplicables | Sí |
| Commits por unidad de trabajo en la rama de una tarea grande | Sí |
| Commits en una tarea pequeña | No, salvo que los pidas |
| Push | No |
| Crear un PR | No |
| Merge | No |
| Publicar o lanzar una versión | No |
| Operaciones destructivas de Git | No, se pregunta antes |
La regla de seguridad del orquestador lo fija: nunca hacer commit salvo que el usuario lo pida explícitamente, con la única excepción de los commits por unidad de trabajo de una implementación ODD sustancial autorizada en su rama de feature.
Los hallazgos no amplían la autorización
Una revisión o verificación puede encontrar más problemas. Las correcciones rutinarias permanecen con su tarea, pero los hallazgos no autorizan por sí solos ampliar el alcance ni se aceptan automáticamente. Un cambio de alcance de negocio requiere tu autorización.
Preguntar poco y preguntar bien
docs/trigger-rules.md define cuándo una pregunta es necesaria: solo cuando la respuesta cambia una de estas cosas.
- El alcance pedido.
- Un impacto destructivo o irreversible.
- La exposición de permisos o seguridad.
- El costo de verificación o los efectos externos.
- El riesgo residual aceptado.
- La entrega.
Si la incertidumbre es técnica y se puede investigar, se investiga. La fuente lo aclara: la incertidumbre técnica pendiente por sí sola no se trata como una nueva decisión humana.
Actividad
Clasifica estos pedidos y justifica cada uno en una línea:
- “Audita los permisos de este endpoint.”
- “Audita los permisos de este endpoint y corrige lo que encuentres.”
- “¿Podrías migrar esto a la nueva API?”
- “Sí, esa opción”, después de que el agente preguntó cuál de dos librerías prefieres.
Una posible solución
- Solo lectura: es una auditoría sin pedido de mutación.
- Autorizado: pide explícitamente corregir, aunque comienza como auditoría.
- Ambiguo: puede ser una consulta de factibilidad o un encargo. Corresponde una aclaración.
- Preferencia confirmada: no autoriza implementar por sí sola, salvo que la propuesta previa fuera una acción concreta de implementación.
Autoevaluación
-
Pides “revisa este PR” y el agente encuentra un bug evidente. ¿Qué corresponde?
- A. Corregirlo porque es evidente
- B. Delegar a un writer para no ensuciar la conversación
- C. Crear un documento de feature para registrarlo
- D. Informarlo sin escribir archivos
-
¿Cuál de estas acciones queda cubierta por un pedido de implementación?
- A. Actualizar la documentación afectada
- B. Hacer push de la rama
- C. Crear el PR
- D. Publicar una versión
-
Un pedido condicional recibe:
- A. Implementación con supuestos marcados
- B. Una aclaración, y el agente sigue en solo lectura
- C. Un documento de feature en estado borrador
- D. Una serie de preguntas hasta cerrar todos los detalles
-
Un “dale” tras una propuesta concreta de implementación:
- A. Autoriza también el merge
- B. Sustituye el consentimiento de una revisión nativa
- C. Autoriza esa acción dentro del alcance acordado
- D. No tiene efecto: se debe repetir la propuesta
Respuestas
- D. La revisión es solo lectura, y un hallazgo no autoriza una mutación.
- A. La documentación necesaria dentro del alcance forma parte del resultado autorizado.
- B. Es la regla literal del paso.
- C. No alcanza a publicación, consentimiento nativo ni acciones destructivas.
Lista de control
- Clasifico un pedido como lectura, cambio o ambiguo.
- Sé que un plan pedido sigue siendo solo lectura.
- Entiendo qué autoriza y qué no autoriza una aprobación corta.
- Tengo claro que implementar no incluye push, PR ni merge.
Fuentes
internal/components/agentguidance/routing.go, internal/assets/skills/_shared/odd-orchestrator-sections.md, docs/trigger-rules.md, docs/quickstart.md.