AgentDock (Trellis Brainstorm)

¿Qué hace AgentDock (Trellis Brainstorm)?

Contrato de Planificación No Negociable

Una solicitud para construir, implementar, corregir, refactorizar o "adelante" no es una aprobación para saltarse la planificación. El consentimiento para crear una tarea tampoco es una aprobación de implementación.

Para cada tarea no trivial, el usuario debe responder al menos una vez después de la solicitud inicial antes de que comience la implementación. Si no se necesita aclaración, esa respuesta debe aprobar el resumen final de planificación descrito a continuación.

Mientras cualquier decisión de producto, alcance, experiencia de usuario (UX), compatibilidad, riesgo o aceptación que pertenezca al usuario permanezca sin resolver, finaliza el turno con exactamente una pregunta de mayor valor. No edites código de producto, no ejecutes implementación ni ejecutes task.py start.

Regla de Evidencia No Negociable

Si una pregunta puede responderse explorando el código base, explora el código base en su lugar.

Esto es obligatorio. Antes de hacer una pregunta al usuario, primero verifica si la respuesta ya está disponible en el código, pruebas, configuraciones, documentación, especificaciones existentes o historial de tareas.

No le pidas al usuario que confirme hechos que el repositorio puede responder. Pregunta solo sobre intención del producto, preferencia, alcance, tolerancia al riesgo, comportamiento de aceptación o decisiones que sigan siendo ambiguas después de la inspección.

La evidencia del repositorio establece el comportamiento actual y las restricciones técnicas. El comportamiento deseado del usuario, los límites del alcance de la funcionalidad y las preferencias de UX nunca son respondibles solo por la evidencia del repositorio, incluso cuando exista un patrón existente; los patrones existentes son opciones y evidencia de recomendación, no decisiones.

---

Usa esta habilidad durante la planificación de la Fase 1 para convertir la solicitud del usuario en requisitos claros y artefactos de planificación.

Precondiciones

Usa esta habilidad solo después de que se haya dado el consentimiento para crear una tarea y el usuario esté listo para ingresar a la planificación de Trellis.

Si aún no existe una tarea, créala:

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<título corto de la tarea>" --description "<resumen de una línea>" --slug <slug>)

Usa un título conciso de la solicitud del usuario. Tanto el título como --description deben ser no vacíos: create rechaza valores en blanco, y un registro con alguno de ellos vacío es rechazado al archivarse. Usa un slug sin prefijo de fecha. task.py create agrega el prefijo de directorio MM-DD- automáticamente.

task.py create crea el prd.md por defecto. Actualiza ese archivo con el entendimiento actual antes de hacer preguntas de seguimiento.

Flujo de Planificación

1. Captura la solicitud del usuario y los hechos conocidos iniciales en prd.md.
2. Inspecciona la evidencia disponible antes de hacer preguntas:
   • código, pruebas, fixtures y configuraciones
   • archivos README, documentación, especificaciones existentes y notas de dominio
   • tareas de Trellis relacionadas, archivos de investigación e historial de sesiones cuando estén presentes
3. Separa lo que encontraste en:
   • hechos confirmados
   • intención del producto aún necesaria del usuario
   • decisiones de alcance o riesgo aún necesarias del usuario
   • elementos probablemente fuera del alcance
4. Si queda una decisión que pertenece al usuario, haz la única pregunta de mayor valor, incluye tu recomendación y compensación, luego detente. No realices trabajo de implementación en el mismo turno.
5. Después de cada respuesta del usuario, actualiza prd.md, recalcula el inventario de decisiones y repite desde el paso 2.
6. Cuando no quede ninguna decisión del usuario, crea o actualiza design.md e implement.md para tareas complejas.
7. Ejecuta la puerta de convergencia de requisitos, luego el pase de convergencia del PRD.
8. Presenta el resumen final de planificación y detente. No ejecutes task.py start ni edites código de producto en el mismo turno.
9. Solo un mensaje posterior del usuario que apruebe explícitamente el último resumen de planificación autoriza task.py start y la implementación. Si los artefactos cambian materialmente después de la aprobación, repite la revisión final.

No inventes una jerarquía de producto/especificación específica del proyecto. Si el repositorio ya tiene documentación de producto, dominio o especificaciones, úsala. Si no la tiene, procede con la evidencia que existe.

Reglas para las Preguntas

Haz solo una pregunta por mensaje.

Cada pregunta debe incluir:

• la decisión necesaria
• por qué la respuesta es importante
• tu respuesta recomendada
• la compensación si el usuario elige de manera diferente

No hagas preguntas de proceso como si buscar, inspeccionar archivos o continuar la lluvia de ideas. Haz el trabajo de evidencia directamente. Pregunta al usuario solo cuando el problema restante sea una decisión de producto, preferencia, límite de alcance o elección de tolerancia al riesgo.

Las recomendaciones no son selecciones predeterminadas. Nunca tomes una decisión de producto recomendada en nombre del usuario solo porque el usuario pidió implementación.

No fabriques preguntas de aclaración cuando la solicitud y la evidencia del repositorio ya resuelvan cada decisión. En ese caso, procede directamente al resumen final de planificación, que aún requiere una aprobación explícita posterior.

La revisión final es una puerta de transición de fase obligatoria, no una pregunta de proceso prohibida. El consentimiento para crear una tarea, la solicitud inicial de implementación y la aprobación dada antes del último resumen final no satisfacen esta puerta.

Marco de Pensamiento: Análisis de Primeros Principios

Cuando los requisitos son vagos, las soluciones parecen sobreingeniería o estás a punto de agregar complejidad "porque todos lo hacen", descompón en verdades fundamentales antes de razonar hacia arriba.

Paso 1: Reformula el Problema

Despoja los detalles de implementación a una oración.

Mal: "Necesitamos agregar almacenamiento en caché con Redis al endpoint del perfil de usuario" Bien: "Los datos del perfil de usuario tardan demasiado en cargarse"

Paso 2: Enumera las Verdades Fundamentales

¿Qué es absolutamente cierto (no opinión o convención)?

Categoría	Ejemplos
Restricciones físicas	La latencia de red ≥ 0, la E/S de disco tiene límites
Reglas de negocio	"Los usuarios deben ver sus propios datos"
Invariantes técnicas	"Los datos deben ser consistentes"
Necesidades del usuario	"El usuario quiere X dentro de Y segundos"

Paso 3: Desafía Suposiciones

Para cada componente del plan actual:

• ¿Hecho o convención? "Siempre usamos REST" — ¿por qué?
• ¿Qué pasa si eliminamos esto? Si nada se rompe, es innecesario.
• ¿Resuelve el problema real o un síntoma? Rastrea la cadena causal.
• ¿Quién se beneficia de esta complejidad? Si "nadie", simplifica.

Paso 4: Construye desde las Verdades

1. Comienza con el mecanismo mínimo viable que satisfaga todas las verdades.
2. Agrega complejidad solo cuando una verdad específica lo exija.
3. Cada adición debe responder: "¿Qué verdad requiere esto?"

Paso 5: Valida

• ¿La solución resuelve el problema original?
• ¿Qué suposiciones necesitan verificación?
• ¿Cuál es el experimento más simple para probar esto?

Puerta de Convergencia de Requisitos

Antes de la revisión final, verifica todo lo siguiente:

• el resultado del usuario y el valor del producto son explícitos
• el comportamiento dentro y fuera del alcance es explícito
• los criterios de aceptación describen resultados observables
• las decisiones de producto, alcance, UX, compatibilidad y riesgo del usuario están resueltas
• las preguntas abiertas bloqueantes están vacías
• las incógnitas técnicas están investigadas o diferidas explícitamente sin cambiar el comportamiento del MVP

Las tareas ligeras pueden omitir design.md e implement.md; no pueden saltarse la inspección de evidencia, la convergencia de requisitos, la revisión final o la aprobación fresca de implementación.

El resumen final de planificación debe mostrar: Objetivo, Dentro del Alcance, Fuera del Alcance, Criterios de Aceptación, Decisiones Clave, Riesgos o Elementos Diferidos Relevantes, y estado de los artefactos.

Reglas de los Artefactos

prd.md registra los requisitos y la aceptación:

• objetivo y valor para el usuario
• hechos confirmados
• requisitos
• criterios de aceptación
• fuera del alcance
• preguntas abiertas que aún bloquean la planificación

design.md registra el diseño técnico para tareas complejas:

• arquitectura y límites
• flujo de datos y contratos
• compatibilidad y notas de migración
• compensaciones importantes
• consideraciones operativas o de reversión

implement.md registra la planificación de la ejecución para tareas complejas:

• lista de verificación de implementación ordenada
• comandos de validación
• archivos riesgosos o puntos de reversión
• verificaciones de seguimiento antes de task.py start

Las tareas ligeras pueden tener solo prd.md. Las tareas complejas deben tener prd.md, design.md e implement.md antes de task.py start.

implement.md no reemplaza a implement.jsonl. En flujos de trabajo de envío a subagentes, implement.jsonl y check.jsonl deben contener cada uno al menos una entrada real de especificación/investigación antes de task.py start; un manifiesto vacío, o uno que contenga solo una fila de marcador de posición _example heredada, no cuenta. Los flujos de trabajo en línea omiten esta puerta JSONL porque la Fase 2 carga el contexto a través de trellis-before-dev.

Pase de Convergencia del PRD

Antes de declarar la planificación lista o ejecutar task.py start, reescribe prd.md una vez contra la estructura final descrita en las reglas de los artefactos anteriores. Esto no es una limpieza opcional; es la puerta final de planificación.

El pase debe ser sin pérdidas:

• Colapsa hechos repetidos en una sección autorizada.
• Dobla secciones temporales de lluvia de ideas como "Lo que ya sé", "Suposiciones" y "Preguntas abiertas" resueltas en Objetivo, Antecedentes, Requisitos, Notas Técnicas o Criterios de Aceptación.
• Elimina preguntas abiertas resueltas en lugar de dejar secciones vacías o ya respondidas.
• Fusiona listas paralelas de errores y requisitos cuando describen el mismo trabajo; mantén la gravedad de cada defecto, la evidencia y los anclajes archivo:línea en el requisito propietario.
• Conserva cada anclaje archivo:línea, decisión, restricción, ID de requisito y mapeo de criterio de aceptación.
• No procedas a la revisión final mientras quede alguna pregunta abierta bloqueante.

Después del pase, lee prd.md de principio a fin y verifica que ningún hecho se repita en todas las secciones a menos que la repetición agregue nueva información.

Nivel de Calidad

Antes de declarar la planificación lista:

• prd.md contiene criterios de aceptación comprobables.
• prd.md ha pasado el pase de convergencia del PRD: sin secciones de lluvia de ideas temporales sin resolver, sin hechos duplicados en todas las secciones y sin anclajes, decisiones o mapeos de aceptación perdidos.
• Las preguntas que el repositorio puede responder ya han sido respondidas mediante inspección.
• Las preguntas abiertas bloqueantes están vacías.
• Las tareas complejas tienen design.md e implement.md.
• Las tareas de envío a subagentes tienen entradas reales curadas tanto en implement.jsonl como en check.jsonl; los manifiestos solo con semillas no están listos.
• El último resumen final de planificación ha sido presentado al usuario.
• En un mensaje posterior, el usuario aprobó explícitamente ese resumen para su implementación.

No comiences la implementación solo porque el usuario originalmente pidió implementación.