ajitta/know-your-unknowns

Bucle de Incógnitas — bucle operativo para trabajar con modelos potentes

Principio fundamental: el cuello de botella con modelos potentes no es el modelo, sino la capacidad del usuario para mantener el mapa (plan) alineado con el territorio (realidad). Esa brecha son las incógnitas. Diseñar el bucle explorar → preguntar → planificar → implementar → registrar desviaciones → verificar es más importante que un buen prompt. Origen: los 11 ejemplos de «Conoce tus incógnitas»; el bucle en sí es una extensión del plugin — ver skills/loop/references/talk-source.md.

Salida: Herramienta Artifact → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → markdown. El artifact de cada etapa mantiene su propio control de reacción; el control del bucle es el punto de control por etapa, que se ensambla en el rastreador .unknowns/loop.json. Detalles: skills/loop/references/output-routing.md

Pasos (10 — escalar según tamaño)

1. Definir valor y criterios de finalización

Acordar con el usuario antes de empezar: propósito / valor para el usuario / criterios de finalización / comportamiento existente que nunca debe romperse / alcance de coste y cambio permitido. Sin criterios de éxito, el volumen de implementación se confunde con el progreso.

2. Investigación de puntos ciegos → /unknowns:blindspot (o /blindspot para instalaciones copiadas)

Solo investigar, sin implementar. Encontrar incógnitas desconocidas, puntos de conflicto, riesgos de regresión; producir un prompt mejorado. Si el dominio en sí no es familiar (solicitudes vagas porque se desconocen términos), ejecutar /unknowns:teach-me junto con esto.

3. Entrevista → /unknowns:interview

Preguntas que cambian la arquitectura primero, máximo 4 por ronda.

4. Explorar soluciones y dar forma (según sea necesario)

• Qué hacer no decidido → /unknowns:brainstorm (mapa del espacio de soluciones)
• No se puede describir cómo debería verse con palabras → /unknowns:prototypes (maquetas divergentes)
• Tiene un ejemplo a emular → /unknowns:reference (análisis de referencia)

5. Prototipo de supuesto arriesgado (según sea necesario)

Antes de la implementación completa, construir un prototipo mínimo que verifique solo el supuesto técnico más incierto. Indicar primero el supuesto y los criterios de éxito/fracaso.

6. Plan → /unknowns:plan

Plan modificable ordenado por probabilidad de revisión, no por orden de ejecución. Las decisiones que necesitan entrada del usuario (esquemas, interfaces, contratos de UX) van arriba.

7. Implementar + registro de desviaciones → aplicar reglas de /unknowns:notes

Registrar todo lo que no esté en el plan; detenerse y preguntar sobre decisiones que toquen arquitectura, comportamiento visible para el usuario, datos o seguridad. Si la conversación se compactó, reinvocar /unknowns:notes (y esta habilidad para la lista de pasos) antes de continuar la implementación.

8. Verificación independiente → agente unknowns:independent-reviewer

Invocarlo con la herramienta Agent (subagent_type: unknowns:independent-reviewer). Nunca un fork o /subtask — esos heredan el contexto del implementador, que es justo lo que este paso existe para excluir. Entregar al agente: criterios de finalización (paso 1), el plan aprobado (paso 6), la ruta de IMPLEMENTATION_NOTES.md, el rango de diff / archivos tocados, y cómo ejecutar las pruebas. Nunca entregarle el resumen del implementador.

9. Verificación de comprensión y traspaso → /unknowns:quiz

Verificar que el usuario pueda explicar este trabajo en un PR o traspaso. Si el trabajo necesita aprobación del revisor o partes interesadas, producir también un documento de /unknowns:buy-in.

10. Revisión de valor

Juzgar por el valor real, no por la calidad del código: el problema de quién se redujo y cuánto / más rápido / razones por las que podría no usarse / métricas / condición de eliminación. Construir es fácil, generar valor sigue siendo difícil. Cerrar capturando una fila de la hoja de puntuación — preguntar al usuario si esto sacó a la luz algo que no sabía y si cambió una decisión, luego agregar la fila a .unknowns/scorecard.md. Nunca responder esas dos preguntas por ellos, y escribir la fila incluso cuando ambas respuestas sean no. Detalles: skills/loop/references/scorecard.md

Criterios de escalado

• Corrección pequeña (1–2 archivos, especificación clara): solo reglas del paso 7 (notas) — no se necesita bucle.
• Trabajo mediano: 1 (un intercambio) → 2 → 3 → 6 → 7 → 9.
• Trabajo grande o desconocido: todos los pasos, con 4 y 5 solo según sea necesario.
• El paso 1 se ejecuta en todos los niveles. Si no está seguro del nivel → preguntar al usuario, luego registrar la elección.

Estado del bucle (sobrevive a compactación, /resume, nuevas sesiones)

Mantener .unknowns/loop.json — {task, tier, stage, decisions[], artifacts[]} — y reescribirlo en cada límite de etapa. Cerrar cada etapa con un punto de control AskUserQuestion (continuar / saltar adelante / detener) y registrar la respuesta allí.

• Argumento status: leer el archivo; informar nivel, etapa actual, pasos restantes.
• Argumento resume: leer el archivo; continuar desde la etapa registrada.
• Cualquier otro texto de argumento es la descripción de la tarea.
• Sin argumento: reanudar .unknowns/loop.json si existe, de lo contrario preguntar primero por la tarea.

Principios operativos (comprimidos)

1. Definir el propósito. 2. Encontrar puntos ciegos antes de implementar. 3. Hacer que el modelo haga preguntas. 4. Dar referencias y prototipos en lugar de palabras. 5. Ordenar planes por probabilidad de revisión. 6. Registrar incógnitas y desviaciones del plan. 7. Verificar con pruebas y revisión independiente. 8. Confirmar que el usuario puede explicar el resultado. 9. Entregables en forma reactable. 10. Medir el valor real, no el volumen de código.