rtaffe28/arch-plan

Plan con arquitectura primero

El plan responde a dos preguntas por encima de todo: cuáles son las piezas y cómo se conectan (diagramas), y cuáles son los contratos exactos entre ellas (interfaces). Las listas de tareas son secundarias; un implementador competente puede derivarlas de buenas interfaces.

Los planes son locales y personales: ~/plans/<YYYY-MM-DD>-<slug>/. El archivo markdown es la fuente de verdad. El Artefacto es una vista del mismo.

1. Entender la solicitud

• Reformula el objetivo en una o dos frases, además de lo que está explícitamente fuera del alcance.
• Si los requisitos son ambiguos, pregunta (ver Hacer preguntas más abajo). Solo pregunta lo que cambiaría el diseño. Haz otra ronda si las respuestas abren nuevas bifurcaciones.
• Cuando una buena opción por defecto dependa de lo que ya hace el código, primero haz un paso rápido del paso 2, para que tus recomendaciones se basen en el repositorio en lugar de ser conjeturas.

Hacer preguntas

Cada pregunta al usuario, en este paso, después del debate y mientras se itera, se realiza a través de la herramienta AskUserQuestion, nunca como una lista en el chat. El usuario debería poder responder la mayoría con un solo clic:

• Pre-rellena una recomendación. Haz que la opción que elegirías sea la primera, con (Recomendado) al final de su etiqueta. Basa tu elección en los patrones existentes del código base, AGENTS.md, y en lo que mantiene el diseño más simple.
• 2–4 opciones concretas por pregunta, cada una una elección real, con una descripción que indique lo que significa para el diseño (por ejemplo, "añade una migración", "reutiliza useCursorFeed"). No añadas una opción "Otro": la herramienta añade una para texto libre.
• Autocontenido. El usuario puede ver solo el diálogo, así que cada pregunta nombra la funcionalidad y la decisión a tomar, y explica brevemente lo que encontraste si eso es lo que motiva la pregunta.
• Hasta 4 preguntas por llamada, con un header chip corto cada una (≤12 caracteres, ej. "Almacenamiento", "Autenticación", "Alcance"). Agrupa preguntas relacionadas; haz otra llamada para el resto.
• Usa multiSelect solo cuando las opciones no sean excluyentes (ej. "¿qué superficies reciben esto?"). Usa preview al comparar artefactos concretos: un esbozo de interfaz, un esquema, un diseño ASCII.
• Si tienes una respuesta clara y la elección es barata de revertir, no preguntes: decide, y regístralo en la tabla de decisiones.

2. Recopilar contexto

En phave-ng (el checkout principal o el worktree del stack):

• Lee primero CLAUDE.md, AGENTS.md y .claude/rules/*. Codifican decisiones que no debes contradecir.
• Encuentra lo que existe: los tipos, servicios, rutas, tablas, trabajos y componentes que la funcionalidad toca o podría reutilizar. Para un barrido amplio, ejecuta agentes Explore en paralelo, uno por área, y conserva solo sus conclusiones.
• Anota cada interfaz existente que extenderás, con su ruta:línea.

3. Dimensionarlo

	Pequeño	Grande
Señales	Una área del código base, aproximadamente un PR (menos de ~400 líneas), sin migración o una trivial	Varias áreas, cambios de esquema, nuevos trabajos en segundo plano, más de un PR, o varias personas o sesiones
Salida	Solo plan.md	plan.md más slices/01-<nombre>.md, slices/02-<nombre>.md, ...

No dividas trabajo pequeño. El ceremonial en un cambio de un solo PR es desperdicio.

Para trabajo grande, corta porciones verticales: cada porción es fusionable por sí sola, deja la rama principal funcionando y entrega algo comprobable. Una "porción" solo de esquema o una "porción de frontend" no es una porción. Ordena las porciones por dependencia y mantén cada una aproximadamente como un PR.

4. Escribir el plan

~/plans/<fecha>-<slug>/plan.md:

# <Título>

**Estado:** Borrador | Aprobado | En progreso | Hecho
**Tamaño:** Pequeño | Grande (N porciones)
**Repo / base:** phave-ng @ <commit>

## Objetivo
<2–3 frases> · **Fuera del alcance:** <viñetas>

## Arquitectura
### Componentes
<Diagrama de flujo Mermaid: piezas existentes en estilo simple, piezas nuevas resaltadas, piezas modificadas marcadas>
### Flujos clave
<Diagrama de secuencia Mermaid para cada flujo importante, incluyendo la ruta de error principal>
### Modelo de datos
<Diagrama ER Mermaid si cambian tablas o columnas; diagrama de estado si algo tiene un ciclo de vida>

## Interfaces
<Todo contrato que la funcionalidad añade o cambia, como código real en el lenguaje del repositorio.
 Marca cada uno como NUEVO o CAMBIADO, con su ruta de archivo de destino.>
- Tipos / modelos de dominio
- Funciones y servicios: firmas completas, más lo que lanzan
- HTTP / acciones de servidor: método, ruta, tipos de solicitud y respuesta, autenticación, códigos de error
- Base de datos: tablas, columnas, índices, política RLS, nombre de migración
- Trabajos / eventos: nombre, tipo de carga útil, idempotencia, reintentos
- Componentes de UI: props, y qué página los renderiza

## Decisiones clave de diseño
| Decisión | Opciones consideradas | Elegida | Por qué |

## Preguntas abiertas
- [ ] <pregunta> — quién puede responderla, y qué cambia según la respuesta

## Porciones        (solo grande)
| # | Porción | Entrega | Depende de | Estado |

## Plan (solo pequeño)
<Pasos ordenados; para cada uno: las interfaces que implementa, archivos, y cómo se prueba>

## Estrategia de prueba
<Lo que se prueba unitariamente y lo que se prueba contra un stack (ver `ai-test` / `manual-test`)>

## Riesgos

Cada slices/0N-<nombre>.md tiene: objetivo, las interfaces de plan.md que implementa (enlázalas, no las copies), archivos, pasos ordenados, criterios de aceptación, pruebas, y Notas de implementación (vacías, las llena implement-plan).

Reglas:

• Los diagramas son Mermaid, con una idea por diagrama. Si uno necesita más de ~12 nodos, divídelo.
• Las interfaces son código, no prosa. Nombra archivos reales. Reutiliza tipos existentes donde puedas, y dílo.
• Cada decisión que un ingeniero razonable podría tomar de forma diferente va en la tabla de decisiones.
• Las incógnitas van en Preguntas abiertas, cada una con la respuesta que recomendarías. No adivines en silencio.

5. Debate crítico / defensor

Lanza dos agentes en paralelo con la herramienta Agent. Dale a cada uno la ruta del plan y los archivos clave del repositorio para leer, no tus conclusiones:

• Crítico: "Encuentra lo que está mal. ¿Cumple el diseño el objetivo? ¿Faltan interfaces, son defectuosas o inconsistentes con los patrones del código base? ¿No son las porciones verdaderamente verticales? ¿Hay una parte sobrediseñada o subespecificada, una reutilización perdida, un modo de fallo, un riesgo de migración, una brecha de permisos? Informa cada problema con una solución concreta."
• Defensor: "Haz la defensa más sólida de las elecciones del plan, especialmente donde se rechazó la alternativa obvia. Nombra lo que es probable que ataque el crítico y por qué se mantiene el diseño actual."

Luego una ronda de réplica: envía a cada agente la salida del otro (SendMessage) y pídele que ceda o mantenga cada punto, con razones.

Tú eres el juez. Por cada punto de controversia:

• Cambio acordado: aplícalo a plan.md / archivos de porción.
• Sin resolver, y necesita al usuario: muévelo a Preguntas abiertas, con la opción que recomendarías.
• Rechazado: mantén la decisión, y registra por qué en la tabla de decisiones.

Añade un ## Resumen del debate a plan.md: punto → crítico → defensor → resolución.

6. Presentar como un Artefacto

Carga artifact-design, y artifact-diagramming para los diagramas. Publica una página para revisión, en este orden:

1. Título, estado, tamaño y un párrafo de resumen
2. Decisiones clave de diseño (la tabla)
3. Preguntas abiertas: lo que necesitas del usuario, de primera clase y fáciles de encontrar
4. Diagramas de arquitectura, renderizados, no texto Mermaid sin procesar
5. Interfaces, como código resaltado, agrupadas por capa, con etiquetas NUEVO / CAMBIADO
6. Porciones (grande) o pasos (pequeño)
7. Destacados del debate: solo los puntos que cambiaron el plan o aún están abiertos
8. La ruta local de plan.md

En el chat, da el enlace. Luego pregunta las preguntas abiertas con AskUserQuestion (ver Hacer preguntas), cada una con las posiciones del crítico y del defensor como opciones y tu recomendación primero.

7. Iterar hasta la aprobación

Las respuestas y comentarios del usuario van primero a plan.md: las preguntas respondidas se mueven de Preguntas abiertas a la tabla de decisiones. Las nuevas preguntas que surjan durante la iteración se hacen de la misma manera, con AskUserQuestion y una opción recomendada. Luego vuelve a publicar el mismo Artefacto (la misma ruta de archivo, para que la URL se mantenga igual). Cuando el usuario apruebe, establece Estado: Aprobado y dirígelo a implement-plan.

No escribas código de producto en esta habilidad.