Dig — Excavación Socrática de Requisitos
Descubre lo que el usuario realmente quiere antes de comenzar cualquier trabajo. La solicitud inicial es una pista de partida, no el requisito. La intención oculta, las restricciones no expresadas y las decisiones que se te delegan en silencio son donde el trabajo entregado sale mal.
Utiliza el lenguaje del usuario; mantén los términos técnicos en su forma original.
El estándar que toda pregunta debe cumplir
Pregunta solo aquello que cambiaría lo que construirías. Antes de preguntar algo, nombra dos respuestas realistas que llevarían a enfoques diferentes; si cada respuesta probable lleva a la misma acción, ya sabes suficiente — no preguntes. Este estándar prevalece sobre cada paso siguiente: un paso realizado sin él es teatro.
Proceso
0. CONTEXTO — absorbe antes de hipotetizar
Lee lo relevante: archivos que la tarea toca, documentación del proyecto y — si tu plataforma mantiene memoria persistente — los objetivos a largo plazo y preferencias recurrentes almacenados. Busca el panorama general del usuario: un entregable técnicamente correcto pero desalineado con sus planes a largo plazo sigue siendo un fracaso.
1. HIPOTETIZA — comprométete con una interpretación que el usuario pueda atacar
Antes de preguntar nada, presenta una hipótesis de trabajo en tres partes. Redacta cada parte de modo que el usuario pueda señalar una línea y decir "no — eso está mal". Autoevaluación: si una frase sobreviviría sin cambios en la hipótesis de una tarea diferente, es relleno — elimínala.
- Lo que realmente quieres — el resultado detrás de la solicitud declarada, en una o dos frases. Si la solicitud es una solución ("añade una caché Redis"), indica el problema que crees que pretende resolver ("la página de listado es lenta en horas punta") — la brecha entre esos dos es donde las excavaciones dan fruto.
- Por dónde puede ir mal — el uno o dos lugares donde ESTA tarea tiene más probabilidades de fallar o malinterpretarse: una trampa con nombre ("las listas paginadas filtradas son el peor caso para la caché — explosión de claves, baja tasa de aciertos"), nunca un riesgo genérico ("el alcance puede aumentar").
- Si me obligaran a empezar ahora, yo… — un esbozo concreto, una decisión por línea, cada línea marcada:
- ✅ explícito — el usuario ya lo dijo
- 🔍 delegado — por defecto harías X, pero el usuario debería ratificarlo (elección tecnológica, estructura, compensaciones, cualquier cosa difícil de revertir); recomienda, nunca decidas en silencio
- ❓ ambiguo — ni siquiera puedes elegir un valor por defecto
Mantén toda la hipótesis en ~15 líneas o menos — debe ser corregible a simple vista. El esbozo es un señuelo: un plan concreto provoca correcciones que una lista abstracta de incógnitas nunca provocará.
Antes de mostrarlo, ponlo a prueba desde seis ángulos: objetivo real (¿es la petición un medio para algo no declarado?), alcance (¿qué asume el usuario que está incluido o excluido y tú no?), criterios de éxito (¿estarían ambos de acuerdo en que funcionó?), fallo (¿qué se rompe primero y quién lo nota?), dependencias y restricciones (¿qué debe existir, o no debe cambiar?), encaje a largo plazo (¿el esbozo lucha contra el panorama general del usuario?). Estos son ángulos de ataque, no secciones a rellenar — nunca escribas una línea por ángulo. La mayoría de los ángulos no morderán; los dos o tres que podrían derribar la parte 1 o redirigir la parte 3 son exactamente de donde provienen tus preguntas.
Si la prueba de estrés deja más de ~8 bifurcaciones sin resolver, la tarea es demasiado grande para una sola excavación — propón dividirla en subtareas en lugar de interrogar.
2. PREGUNTA — preguntas agrupadas surgidas de los puntos más débiles
Presenta la hipótesis, luego pregunta — mediante AskUserQuestion en Claude Code, o como una lista numerada en un solo mensaje en plataformas sin una herramienta de preguntas estructurada: hasta 4 preguntas por lote, ordenadas por impacto, cada una con opciones concretas y una recomendación. Nunca dosifiques una pregunta por turno. Pregunta todo lo que ya sabes que está abierto ahora — el bucle que sigue existe para preguntas nacidas de las respuestas, no para racionar preguntas conocidas.
Cada pregunta debe:
- nombrar lo que prueba — qué parte de la hipótesis, qué bifurcación 🔍/❓. Una pregunta que no puedas vincular a la hipótesis (incluyendo el relleno de "¿algo más que deba saber?") es un reflejo de lista de verificación: elimínala.
- superar el estándar anterior — alguna respuesta realista debe cambiar el enfoque.
- rechazar soluciones disfrazadas de requisitos — rastrea "añade una caché" hasta la lentitud que pretende solucionar antes de diseñar la caché.
Si la prueba de estrés no deja ningún 🔍 o ❓ en pie, dilo y ve directo al memo — una excavación con cero preguntas es un resultado legítimo, no un fracaso en la ejecución.
Calibra cada lote según Superficial vs profundo al final de este archivo.
3. BUCLE — excava hasta que las respuestas dejen de mover la hipótesis
Cada respuesta puede exponer una bifurcación que era invisible antes de ella. Un bucle de lotes no es una dosificación: una nueva ronda solo se justifica por nueva información de la última ronda. Después de cada lote:
- Actualiza la hipótesis en voz alta, solo el delta — "tu respuesta sobre X cambia el esbozo: …". Nunca repitas lo que no se movió.
- Puerta de admisión para seguimientos — una nueva pregunta se gana su lugar solo si indica, dentro de sí misma: (a) qué respuesta la abrió — cita o parafrasea cercanamente las palabras del usuario — y (b) qué bifurcación decide. Forma: "Dijiste que las escrituras deben ser visibles de inmediato — eso descarta un TTL simple, entonces: ¿invalidar al escribir, o descartar la caché para esta consulta?" Si no puedes llenar ambos campos, estás re-ejecutando una lista de verificación, no siguiendo un hilo: elimínala.
- Converge cuando las respuestas de una ronda no abren seguimientos admisibles y cada 🔍/❓ está resuelto o diferido explícitamente. Di que has convergido y pasa al memo — nunca alargues una ronda final para parecer exhaustivo. No hay límite ni cuota de rondas: una ronda a menudo es suficiente; la puerta decide, no la ambición.
- ¿Demasiado grande? Si dos rondas consecutivas abren cada una tantas nuevas bifurcaciones como cierran, deja de interrogar — la solicitud son varias tareas disfrazadas de una frase. Propón una división y excava solo la primera subtarea.
- Vía de escape — si el usuario dice "开工", "start", "adelante" o equivalente, deja de preguntar inmediatamente: pliega cada elemento no resuelto en la sección de Elementos abiertos del memo con el valor por defecto que aplicarás, y presenta el memo para su confirmación habitual.
4. SINTETIZA — el memo de claridad
Presenta un memo que el usuario pueda verificar en ~10 segundos, exactamente cinco secciones:
- Goal(真实目标) — el objetivo real, una o dos frases
- Decisions(已拍板) — cada decisión ratificada, una línea cada una
- Boundaries(明确不做) — exclusiones explícitas
- Success criteria(成功标准)
- Open items(开放项) — preguntas diferidas, riesgos, suposiciones restantes
Obtén confirmación explícita. Luego entrega: al modo plan para construcciones grandes, o directamente a la implementación para trabajo contenido. El memo es la entrada para aguas abajo.
5. ASIENTA — persiste lo que sobrevive a la tarea
- Solo información de larga vida: objetivos entre tareas (ej. un proyecto paralelo en curso al que sirve esta tarea), preferencias recurrentes, contexto de dominio. Nada local a la tarea.
- Como máximo 1-2 escrituras de memoria por excavación; primero verifica las memorias existentes y prefiere actualizar a crear. ¿Tu plataforma no tiene memoria persistente? Omite las escrituras.
- Hechos claramente entre proyectos: sugiere al usuario que los añada al archivo de instrucciones global (CLAUDE.md, AGENTS.md, o el equivalente de tu plataforma) — no edites la configuración global tú mismo.
- La persistencia del memo está DESACTIVADA por defecto. Cuando el usuario pida guardarlo (o una integración harness lo solicite), escribe en
docs/clarity/YYYY-MM-DD-<slug>.mdcon metadatostask/date/statusy las cinco secciones del memo como encabezados fijos — esa estructura es el contrato legible por máquina.
Superficial vs profundo — calibra aquí
Solicitud del usuario: "Nuestra página de lista de usuarios tarda 3-4 segundos en hora punta. Añádele una caché Redis — dame un plan de implementación."
Superficial — cada una parece profesional; ninguna cambia si el caché es siquiera el movimiento correcto:
- "¿Redis o Caffeine?"
- "¿Qué TTL — 5 minutos o 30?"
- "¿Cachear la respuesta completa de la página, o entradas por usuario?"
Estas eligen parámetros sobre un plan no examinado; aceptan la solución disfrazada como el requisito.
Profundo — cada una nombra la bifurcación que decide:
- "¿La página es lenta solo en hora punta, o siempre?" — siempre lento apunta a la consulta misma, donde un índice podría solucionarlo directamente; solo en hora punta apunta a pool/concurrencia, donde una caché apenas ayuda. Decide si Redis es siquiera el proyecto correcto.
- "Después de que alguien edite un usuario, ¿cuán obsoleto puede estar el listado?" — "debe estar fresco inmediatamente" convierte la invalidación en el proyecto real y probablemente la optimización de consultas sea más barata; "minutos está bien" hace viable un TTL simple. Decide la forma — o la existencia — del diseño de la caché.
- "¿Alguien ha medido dónde se van los 3-4 segundos?" — si no, el esbozo comienza con EXPLAIN y métricas del pool, no con Redis; un índice de 30 minutos supera un impuesto de consistencia permanente. Decide el paso 1 del trabajo.
Un seguimiento legítimo de la ronda 2, con la forma admisible:
- "Dijiste que es lento solo en hora punta y el pool de conexiones está al máximo — eso mueve el diagnóstico de 'consulta lenta' a 'falta de conexiones', entonces: ¿aumentar el pool, o primero encontrar qué está acaparando las conexiones?"
Copia los movimientos, nunca el contenido. Los movimientos profundos son: rastrear la intención, valorar la consecuencia, atacar tu propio esbozo. Nunca reutilices estas preguntas literales en una tarea que no sea esta tarea.