Pasos 2 y 3: Explorar y resolver incertidumbre
Pasos 2 y 3: Explorar y resolver incertidumbre
Objetivos
- Explorar en proporción al pedido, sin duplicar lecturas.
- Decidir cuándo investigar, cuándo preguntar y cuándo desafiar una premisa.
- Aplicar los requisitos de calidad a la evidencia externa.
Paso 2: Explorar
Se explora el código y los requisitos existentes antes de proponer o escribir. Dos palabras gobiernan este paso.
Proporcionalmente. La profundidad se adapta a la incertidumbre y a la consecuencia. La fuente descarta los cuestionarios fijos y las rondas obligatorias.
Mapa. Una exploración separada existe para producir un mapa que hace falta para decidir o enrutar. La regla contraria es igual de explícita:
Explore only for a map you need to decide or route, never to read files you will read anyway before writing inline.
internal/components/agentguidance/routing.go
flowchart TD
A["Necesito entender algo"] --> B{"¿Cabe en una tanda?<br/>hasta 3 llamadas y ~10k tokens"}
B -->|"Sí"| C["Leer inline"]
B -->|"No, o más de ~5 búsquedas secuenciales"| D["Un explorador de solo lectura"]
D --> E["Mapa de hasta ~2k tokens<br/>con evidencia path:line"]
E --> F["Una comprobación del parent"]
F --> G["Reevaluar el tamaño de la tarea"]Lecturas que corresponden a quien escribe
Hay un error típico: delegar un explorador para leer los archivos y luego leerlos de nuevo para escribir. La sección de verificación compartida lo resume: la lectura que prepara una escritura le corresponde a quien haga esa escritura. Si el parent escribe inline, lee inline. Si delega a un writer, el writer lee.
Reutilizar lo investigado
Otras dos reglas del texto canónico reducen el gasto:
- Validar las premisas relevantes contra la evidencia disponible antes de construir.
- Reutilizar la investigación relacionada ya hecha en lugar de repetirla.
Herramientas de exploración
El explorador de OpenCode prefiere la herramienta codegraph_explore cuando hay un índice de CodeGraph y usa read, grep y glob como alternativa cuando esa herramienta no está disponible o falla. Otros runtimes usan su mecanismo propio. El explorador nunca crea el índice: gentle-ai codegraph init es una acción del parent.
Paso 3: Las tres herramientas de incertidumbre
El paso completo cabe en una oración del código fuente, compartida textualmente por todos los runtimes:
Recommend optional research only for a named uncertainty; ask one focused user question only for a real unresolved product decision, then stop and wait; use at most one scoped read-only assumption challenge for a high-consequence unproven premise.
flowchart TD
A["Queda una duda"] --> B{"¿De qué tipo?"}
B -->|"Técnica y se puede investigar en el código"| C["Seguir explorando"]
B -->|"Necesita evidencia externa"| D["Investigación opcional"]
B -->|"Decisión de producto real"| E["Una pregunta y esperar"]
B -->|"Premisa no demostrada<br/>de alta consecuencia"| F["Un desafío de supuestos"]
B -->|"Falla determinista"| G["Arreglar, sin debate"]Investigación opcional
No hay fase de investigación obligatoria. Se recomienda cuando una pregunta sin resolver se beneficia de evidencia externa. Si la declinas, el trabajo continúa dentro del alcance autorizado en lo que sea seguro, la incertidumbre se declara y se pausan las decisiones inseguras que dependen de ella.
Los requisitos de research-lifecycle.md y del texto canónico para una investigación son concretos:
| Requisito | Significado |
|---|---|
| Fuentes primarias | Se prefieren cuando existen |
| Atribución | Cada afirmación relevante se atribuye a una URL o ubicación en el código |
| Separación | Se distinguen hechos verificados, supuestos, contradicciones, vigencia y vacíos |
| Honestidad de acceso | Si una herramienta no está disponible se declara y nunca se inventa acceso ni evidencia |
| Permisos | No se deduce acceso del nombre de una herramienta ni se saltan los permisos configurados |
| Entrega | Hallazgos concisos, recomendación, tradeoffs, preguntas abiertas e implicaciones |
También hay límites para que no se convierta en un proceso:
- Sigue siendo solo lectura y sus hallazgos no autorizan implementar.
- Se delega a un worker general de exploración, sin crear un agente de investigación especializado.
- No introduce un comando nuevo ni exige persistencia: los resultados quedan en la conversación salvo que pidas lo contrario.
- Una propuesta es útil solo para una decisión real, no es un paso obligatorio.
La pregunta enfocada
La pregunta está reservada para una decisión de producto o diseño real y sin resolver. La mecánica es estricta: una pregunta, enfocada, y luego detenerse a esperar.
Esto se conecta con el Ask trigger del capítulo 11 y con dos reglas de propiedad:
- El parent es dueño de las decisiones de producto.
- Los workers devuelven los vacíos al parent y no eligen ni entrevistan al usuario.
Ejemplos de la diferencia:
| Duda | ¿Se pregunta? | Motivo |
|---|---|---|
| ”¿Los filtros actuales están en este módulo o en aquel?” | No | Se resuelve leyendo el código |
| ”¿El CSV incluye datos que solo ven los administradores?” | Sí | Decisión de producto con impacto de seguridad |
| ”¿Qué nombre interno le pongo a esta función?” | No | Decisión técnica menor |
| ”¿Se exporta todo o solo la página visible?” | Sí, si el pedido no lo define | Cambia el resultado para el usuario |
El desafío de supuestos
Es la herramienta menos habitual. Una premisa no demostrada de alta consecuencia puede recibir una verificación independiente de solo lectura, incluso en un cambio pequeño cuando es crítico para la seguridad. El texto pide tres elementos: nombrar la premisa, la evidencia y la consecuencia. También limita su forma:
- No se abre un ciclo de debate.
- Las fallas deterministas se arreglan: no se discuten entre modelos.
- En runtimes con RDD, el refutador nativo es el dueño de las afirmaciones de la revisión nativa, y no se duplica ni se evita.
Un ejemplo sería asumir que un token de servicio no se registra en ningún log antes de cambiar cómo se genera. El desafío buscaría evidencia en contra de esa premisa antes de construir sobre ella.
Cuándo pausar y cuándo seguir
La fuente insiste en no convertir una duda en un bloqueo general:
- Las tareas independientes dentro del alcance continúan.
- Solo se pausa lo que depende de la decisión abierta o de la evidencia faltante.
- Si faltan herramientas opcionales, no se reintenta sin fin ni se detiene todo por eso: se declara la limitación.
Actividad
Toma el pedido grande del capítulo 1. Escribe:
- Una incertidumbre técnica que resolverías explorando.
- Una pregunta de producto real, formulada en una sola oración.
- Una premisa de alta consecuencia que merecería un desafío, indicando evidencia y consecuencia.
Si no encuentras ninguna para el punto 3, también es un resultado válido: esa herramienta es excepcional.
Autoevaluación
-
¿Cuándo se justifica un explorador separado?
- A. Siempre que la tarea toque varios archivos
- B. Para leer los archivos que el parent editará luego inline
- C. Cuando se necesita un mapa para decidir o enrutar y excede el presupuesto inline
- D. Al inicio de toda tarea grande
-
¿Cuántos desafíos de supuestos admite una premisa?
- A. Uno como máximo
- B. Dos, uno por cada modelo
- C. Los necesarios hasta llegar a un acuerdo
- D. Ninguno en cambios pequeños
-
Un test falla de forma determinista. ¿Qué indica la fuente?
- A. Abrir un desafío de supuestos
- B. Hacer una pregunta de producto
- C. Pedir una investigación externa
- D. Arreglarlo, sin debate entre modelos
-
Declinaste una investigación recomendada. ¿Qué ocurre?
- A. El trabajo se detiene por completo
- B. Continúa lo seguro dentro del alcance, se declara la incertidumbre y se pausan las decisiones inseguras
- C. El agente la ejecuta igualmente en segundo plano
- D. Se crea un documento de feature para registrarla
Respuestas
- C. La regla prohíbe explorar para leer lo que se leerá de todas formas.
- A. “At most one” aparece en el protocolo.
- D. “Deterministic failures need fixes, not model debate.”
- B. Es la conducta descrita en la sección de ODD del texto canónico.
Lista de control
- Sé cuándo leo inline y cuándo pido un mapa.
- Separo dudas técnicas de decisiones de producto.
- Puedo exigir atribución y distinción de hechos en una investigación.
- Entiendo por qué el desafío de supuestos tiene límite de uno.
Fuentes
internal/components/agentguidance/routing.go, internal/assets/skills/_shared/research-lifecycle.md, internal/assets/skills/_shared/odd-orchestrator-sections.md, internal/assets/opencode/agents/gentle-ai-explore.md, docs/usage.md.