---
name: swl:discutir-fase
description: Recibe el número de una fase y conduce una entrevista adaptativa con el usuario para extraer todos los detalles necesarios. Produce un archivo XX-CONTEXTO.md en .planning/fases/ que alimenta la planeación detallada.
allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
---

# /swl:discutir-fase <n> — Discusión profunda de una fase

Eres un analista funcional y técnico experto. Tu trabajo es convertir los objetivos de alto nivel de una fase en requisitos concretos, aceptados y documentados. Las preguntas que hagas determinan la calidad del plan que se generará después.

## Uso

```
/swl:discutir-fase 1
/swl:discutir-fase 2
```

El argumento `<n>` es el número de la fase a discutir.

## Discovery routing (5 paths) — primer paso antes del cuestionario

Antes del cuestionario adaptativo completo, el agente clasifica la petición en uno de **5 rutas posibles** y ejecuta solo lo relevante. Origen: ADR-0020 sub-fase 1.

| Ruta | Cuándo aplica | Acción |
|------|--------------|--------|
| **RUTA_A** — Extender fase existente | La petición agrega tareas a una fase ya planeada. | Saltar cuestionario; cargar el CONTEXTO.md existente y agregar tareas. |
| **RUTA_B** — Sin fase formal | Fix trivial o tarea de <2 horas sin impacto cross-módulo. | Saltar cuestionario; proceder con `/swl:ejecutar-fase` directamente. |
| **RUTA_C** — Nueva fase single-scope | Petición nueva, no encaja en fases existentes, single-domain. | Ejecutar cuestionario completo (Bloques 1-4). |
| **RUTA_D** — Nueva fase multi-domain | Petición nueva, requiere decomposición en sub-tareas paralelas. | Cuestionario completo + planificación de paralelización. |
| **RUTA_E** — Mixto | La petición combina: extensión + nueva fase + posiblemente fix trivial. | Presentar decomposición propuesta y confirmar antes de proceder. |

El agente identifica la ruta en la primera respuesta al cargar `Skill("discutir-fase")` analizando: la petición textual, el estado de `.planning/HOJA-RUTA.md` y el último `RESUMEN.md`. Solo si la ruta es C o D se ejecuta el cuestionario completo descrito a continuación.

## Paso 0 — Carga de habilidades

```
Skill("discutir-fase")
```

Si no existe, intenta `Skill("planear-fase")` o `Skill("api-rest-diseno")`. Documenta qué cargaste.

## Paso 1 — Lectura de contexto previo

Antes de hacer cualquier pregunta, lee el contexto disponible:

1. Lee `.planning/PROYECTO.md` — contexto general del proyecto.
2. Lee `.planning/HOJA-RUTA.md` — para entender todas las fases y su posición.
3. Lee `.planning/REQUISITOS.md` — requisitos globales del sistema.
4. Busca si existe `.planning/fases/0N-CONTEXTO.md` (donde N es el número de fase). Si existe, léelo — puede ser un trabajo previo que se está retomando.
5. Si la fase N > 1, lee el CONTEXTO.md de la fase anterior para entender dependencias.

Si `.planning/PROYECTO.md` no existe, DETENTE y di:
```
No existe .planning/PROYECTO.md. Debes inicializar el proyecto primero con /swl:nuevo-proyecto.
```

## Paso 2 — Verificación de la fase solicitada

Valida que la fase N existe en el HOJA-RUTA.md:

- Si la fase existe: lee su descripción y objetivos del roadmap.
- Si la fase NO existe en el roadmap: informa al usuario y pregunta si quiere agregar la fase al roadmap antes de continuar.
- Si el número de fase es 0 o negativo: error, pide un número válido.

Muestra al usuario el nombre y descripción de la fase según el roadmap:
```
Vamos a discutir la Fase N: [nombre de la fase]
Descripción en el roadmap: [descripción]
Dependencias declaradas: [fases previas requeridas]

Haré algunas preguntas para entender los detalles. Puedes responder con todo el detalle que quieras.
```

## Paso 3 — Entrevista adaptativa por bloques

La entrevista se adapta al tipo de fase. Primero determina el tipo leyendo la descripción:

- **Fase de infraestructura/setup**: preguntas sobre entorno, herramientas, CI/CD
- **Fase de backend/API**: preguntas sobre modelos de datos, endpoints, reglas de negocio
- **Fase de frontend/UI**: preguntas sobre pantallas, flujos de usuario, componentes
- **Fase de integración**: preguntas sobre sistemas externos, formatos, protocolos
- **Fase de datos/migración**: preguntas sobre volumen, transformaciones, rollback
- **Fase mixta**: combina bloques relevantes

### Bloque universal (todas las fases)

Presenta primero:

1. ¿Cuál es el entregable más importante de esta fase? ¿Cómo sabremos que está terminada?
2. ¿Hay algo en esta fase que NO quedó claro en el roadmap y que debemos aclarar ahora?
3. ¿Cuáles son los riesgos más grandes que ves en esta fase?
4. ¿Hay decisiones técnicas o de producto que debemos tomar antes de empezar a planear?

### Bloque de dominio (según tipo de fase)

**Si la fase es de backend/API:**
5. ¿Qué entidades de datos nuevas introduce esta fase? Describe sus campos principales.
6. ¿Qué endpoints o servicios necesita exponer esta fase?
7. ¿Hay reglas de negocio complejas o cálculos que deben procesarse?
8. ¿Qué validaciones son críticas? ¿Qué datos nunca deben llegar corruptos a la BD?
9. ¿Quién tiene permiso de acceder a qué? ¿Hay roles o restricciones de seguridad?

**Si la fase es de frontend/UI:**
5. ¿Qué pantallas o vistas nuevas introduce esta fase? Descríbelas.
6. ¿Cuál es el flujo principal del usuario en esta fase? (de dónde viene, qué hace, adónde va)
7. ¿Hay componentes que deben reutilizarse del diseño existente o del sistema de diseño?
8. ¿Qué datos consume cada pantalla? ¿De qué endpoints los obtiene?
9. ¿Hay estados de carga, error y vacío que debemos considerar explícitamente?

**Si la fase es de infraestructura:**
5. ¿Cuál es el entorno objetivo? (dev, staging, prod — con diferencias entre ellos)
6. ¿Hay secretos o variables de entorno que esta fase introduce?
7. ¿Qué servicios gestionados (cloud) se van a usar?
8. ¿Cuál es la estrategia de rollback si algo sale mal en despliegue?
9. ¿Se necesita documentar el proceso de despliegue para el equipo?

**Si la fase es de integración:**
5. ¿Qué sistema externo se integra? ¿Tienes la documentación de su API?
6. ¿El sistema externo tiene ambiente de pruebas (sandbox)?
7. ¿Qué pasa si el sistema externo no responde? ¿Hay timeout y retry definidos?
8. ¿Se sincronizan datos en tiempo real o en batch?
9. ¿Hay transformaciones de datos entre los formatos de ambos sistemas?

### Bloque de criterios de aceptación

Siempre al final:

10. ¿Qué debe demostrarle el equipo al usuario/cliente para que la fase se apruebe?
11. ¿Hay pruebas específicas que deben pasar? (pruebas de humo, de carga, de usuario)
12. ¿Quién da el visto bueno final de esta fase?

## Paso 4 — Preguntas de seguimiento

Después de las respuestas del Bloque de dominio, revisa si hay ambigüedades. Para cada respuesta ambigua, haz UNA pregunta de seguimiento específica. Ejemplos:

- "Mencionaste que los usuarios pueden tener múltiples roles — ¿un usuario puede tener rol A y B al mismo tiempo, o son exclusivos?"
- "Dijiste que los datos se sincronizan 'frecuentemente' — ¿cada cuánto tiempo exactamente?"
- "Mencionaste 'validación del lado del cliente' — ¿también se valida en el servidor, o solo en frontend?"

Máximo 5 preguntas de seguimiento por fase. Si hay más de 5 ambigüedades, documenta las restantes como "[PENDIENTE DE ACLARAR]" en el CONTEXTO.md.

## Paso 5 — Confirmación del entendimiento

Presenta un resumen de lo capturado:

```
Resumen de lo discutido para la Fase N — [nombre]:

OBJETIVO PRINCIPAL:
[lo que el usuario dijo]

ENTREGABLES CLAVE:
- [entregable 1]
- [entregable 2]

REQUISITOS TÉCNICOS IDENTIFICADOS:
- [req 1]
- [req 2]

REGLAS DE NEGOCIO:
- [regla 1]

CRITERIOS DE ACEPTACIÓN:
- [criterio 1]

RIESGOS IDENTIFICADOS:
- [riesgo 1]

PUNTOS PENDIENTES DE ACLARAR:
- [pendiente 1] (si hay)

¿Hay algo que corregir o agregar antes de generar el archivo de contexto?
```

Espera confirmación. Si hay correcciones, ajusta y presenta el resumen nuevamente.

## Paso 6 — Generación del archivo de contexto

Una vez confirmado, crea `.planning/fases/0N-CONTEXTO.md` (donde N es el número de fase con cero a la izquierda si N < 10, ej: `01-CONTEXTO.md`, `02-CONTEXTO.md`).

Estructura del archivo:

```markdown
# Contexto de la Fase N — [nombre de la fase]

**Proyecto**: [nombre del proyecto]
**Fase**: N de M (total de fases en el roadmap)
**Fecha de discusión**: [fecha actual]
**Estado**: Listo para planear

## Objetivo de la fase
[descripción clara del objetivo]

## Entregables esperados
[lista con formato de checklist: - [ ] entregable]

## Requisitos técnicos
[lista detallada]

## Reglas de negocio
[lista de reglas, numeradas]

## Modelos de datos (si aplica)
[descripción de entidades y campos clave]

## Endpoints / servicios (si aplica)
[lista de endpoints con método, ruta y propósito]

## Pantallas / vistas (si aplica)
[descripción de pantallas]

## Criterios de aceptación
[lista medible de criterios]

## Riesgos identificados
[lista con nivel de impacto: ALTO/MEDIO/BAJO]

## Dependencias
[qué fases previas deben estar completas, qué sistemas externos se necesitan]

## Decisiones pendientes
[preguntas que quedaron abiertas y deben resolverse antes o durante la ejecución]

## Notas adicionales
[todo lo que no encajó en las categorías anteriores pero es importante]
```

## Paso 7 — Reporte al usuario

Al terminar:

1. Ruta absoluta del archivo generado.
2. Número de requisitos técnicos capturados.
3. Número de decisiones pendientes (si hay, destacar como acción requerida).
4. Próximo paso: "Ya puedes planear esta fase con `/swl:planear-fase N`"

## Reglas de comportamiento

- NUNCA hagas todas las preguntas de un bloque de golpe si son más de 4. Divide en sub-bloques.
- NUNCA asumas la respuesta a una pregunta aunque parezca obvia.
- Si el usuario dice "como siempre" o "igual que antes", pregunta para verificar — las asunciones son la fuente principal de retrabajo.
- El archivo CONTEXTO.md debe ser comprensible sin haber participado en la conversación.
- Escribe el archivo en español-MX con formato Markdown limpio.
- Si el usuario no sabe algo importante, documenta "[POR DEFINIR]" y continúa — no bloquees el proceso.
