---
name: discutir-fase
description: Cuestionario adaptativo que se ejecuta antes de planear una fase de desarrollo. Extrae decisiones técnicas y de negocio del usuario, clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un archivo CONTEXTO.md que alimenta al planificador. Inicia con discovery routing (5 paths) que evita el cuestionario completo cuando no aplica.
version: "1.1.0"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar si el usuario ya tiene un CONTEXTO.md poblado para la fase en curso — ir directo a `planear-fase`."
  - "No cargar para tareas one-shot que no forman parte de un plan de fases (ej: 'arregla este bug')."
  - "No cargar para diagnóstico rápido o exploración libre; en ese caso usar `workflow-claude-code` o simplemente conversar."
  - "No cargar si la fase ya está en ejecución y se busca retomar el estado; usar `ejecutar-fase` + ESTADO.md."
evolvable: true  # default para skill estandar
---
# Habilidad: Discutir Fase Antes de Planear

## Propósito

El planificador no puede crear un plan ejecutable sin contexto de decisiones.
Esta habilidad hace las preguntas correctas, en el orden correcto, para extraer
ese contexto antes de que se escriba una sola línea del PLAN.md. Evita el
antipatrón de planear con suposiciones implícitas que luego se contradicen.

## Cuándo activar

- Antes de ejecutar la habilidad `planear-fase`
- Cuando el usuario dice "vamos a la siguiente fase" sin dar detalles
- Cuando el HOJA-RUTA.md describe una fase de forma vaga
- Cuando hay decisiones de diseño no resueltas que bloquean el plan

## Cuándo NO cargar

- El CONTEXTO.md de la fase ya existe en `.planning/fases/` con decisiones cerradas — ir directo a `planear-fase`.
- El usuario pide hacer una tarea puntual sin ciclo de fases formal (no tiene HOJA-RUTA.md).
- La fase ya está en ejecución; las preguntas de esta habilidad son pre-planeación, no retoma. Usar `ejecutar-fase`.
- El usuario quiere diagnóstico rápido de qué sigue; no se necesita el cuestionario completo, basta revisar HOJA-RUTA.md.

---

## Paso 0 — Discovery routing (obligatorio antes del cuestionario)

Antes de lanzar el cuestionario adaptativo, ejecuta **scan ligero** de
`.planning/` para identificar la ruta correcta. Esto evita gastar turnos en
un cuestionario cuando la petición del usuario no requiere una fase nueva.

Inspirado en `kiro-discovery` (cc-sdd) — ver `temp/cc-sdd-main/tools/cc-sdd/templates/agents/claude-code-skills/skills/kiro-discovery/SKILL.md`.

### Inventario rápido (solo metadata, NO leer contenido completo)

1. `Glob` sobre `.planning/fases/*.md` → lista de fases existentes y su estado.
2. `Read` de `.planning/HOJA-RUTA.md` (si existe) — para mapear la petición a roadmap.
3. `Read` del `.planning/ESTADO.md` (si existe) — para conocer fase activa.

Si no hay `.planning/`, marca **proyecto verde** y salta al cuestionario completo (Ruta C por defecto).

### Determinar la ruta

| Ruta | Cuándo aplica | Acción |
|------|--------------|--------|
| **RUTA_A** — Extiende fase existente | La petición es una extensión, fix o enhancement dentro del scope de una fase ya planeada. Cabe en `tasks` de un PLAN.md existente. | NO ejecutar cuestionario. Informar al usuario: "Esto encaja en la fase `<N>`. ¿Procedo a actualizar su PLAN.md o lanzar `/swl:ejecutar-fase <N>` directo?" |
| **RUTA_B** — Sin fase necesaria | Fix trivial (<5 archivos, 1 tarea, sin decisiones de scope). Bug puntual, typo, dependencia, refactor menor. | NO ejecutar cuestionario. Informar al usuario: "Esto no requiere fase formal. Procedo directo con `implementador-swl` o el agente de stack. ¿De acuerdo?" |
| **RUTA_C** — Nueva fase single-scope | Petición nueva, no encaja en fases existentes, single-domain. | Ejecutar cuestionario completo (Bloques 1-4). |
| **RUTA_D** — Decomposición multi-fase | Petición spans múltiples dominios o produciría >20 tareas en una sola fase. | Ejecutar cuestionario **resumido** (Bloque 1 + Bloque 4) para extraer decisiones de scope. Luego sugerir descomposición en N fases. Confirmar con usuario antes de proceder. |
| **RUTA_E** — Mixto | La petición combina: extensión de fase existente + nueva fase + posiblemente fix trivial. | Presentar al usuario la decomposición propuesta y confirmar antes de proceder. Para la parte "nueva fase" ejecutar cuestionario reducido. |

### Heurísticas de matching

- Si la petición menciona explícitamente "fase N" → considerar RUTA_A primero.
- Si la petición empieza con "arregla", "corrige", "fix", "elimina" → considerar RUTA_B primero.
- Si la petición empieza con "implementa", "crea", "agrega feature" → RUTA_C o RUTA_D.
- Si la petición tiene `y`, `,`, `también` enumerando >2 cosas distintas → RUTA_D o RUTA_E.

### Cómo presentar el veredicto

Tras el scan, emite un mensaje corto al usuario antes del cuestionario:

```
Discovery routing: RUTA_<X>
Justificación: <una oración explicando por qué>
Próximo paso: <qué se hará a continuación>
¿Procedo? [s/N o sugerir otra ruta]
```

Solo después de confirmar la ruta procede con el cuestionario (si aplica).

---

## Protocolo de entrevista adaptativa

### Regla 1 — Máximo 4 preguntas por mensaje

No bombardear al usuario. Agrupa preguntas relacionadas. Espera respuesta antes
de continuar con el siguiente bloque.

### Regla 2 — Clasifica cada respuesta al recibirla

| Tipo | Definición | Cómo registrar |
|------|-----------|---------------|
| CERRADA | Decisión no negociable del usuario | `[CERRADA]` en CONTEXTO.md |
| ABIERTA | El usuario delega la decisión al agente | `[ABIERTA - decisión del agente]` |
| PENDIENTE | Sin respuesta todavía | `[PENDIENTE - bloquea plan]` |

### Regla 3 — No avanzar con PENDIENTE en ítems críticos

Si una decisión es crítica para el plan y está marcada PENDIENTE, detente y
notifica explícitamente antes de proceder.

---

## Bloque 1 — Contexto de la fase (siempre preguntar)

1. ¿Cuál es el objetivo principal de esta fase en una oración?
2. ¿Qué debe existir y funcionar al finalizar esta fase para considerarla exitosa?
3. ¿Hay alguna restricción de tiempo (deadline, demo, sprint)?
4. ¿Alguna decisión tomada en fases anteriores afecta el alcance de esta?

---

## Bloque 2 — Decisiones técnicas (preguntar si aplica)

Preguntar solo si la fase involucra código nuevo o cambios de arquitectura:

5. ¿Se crean nuevas entidades de base de datos? ¿Cuáles?
6. ¿Se expone una nueva API pública o se modifican endpoints existentes?
7. ¿Hay integraciones con sistemas externos en esta fase?
8. ¿Se espera algún cambio en la autenticación o los permisos?
9. ¿Hay requerimientos de rendimiento específicos para esta fase?

---

## Bloque 3 — Calidad y proceso (preguntar si aplica)

Preguntar si el equipo tiene proceso definido o si la fase es crítica:

10. ¿Se requieren tests unitarios, de integración o ambos en esta fase?
11. ¿Hay features que requieren revisión de seguridad antes de merge?
12. ¿Se va a hacer deployment de esta fase de forma independiente o junto con otras?
13. ¿Hay features marcadas como "nice to have" que pueden salir del scope si hay tiempo?

---

## Bloque 4 — Dependencias y riesgos (siempre preguntar)

14. ¿Hay tareas en esta fase que dependen de trabajo de otro equipo o sistema externo?
15. ¿Hay algún riesgo técnico conocido que podría bloquear alguna tarea?
16. ¿Hay deuda técnica existente que DEBE resolverse antes o durante esta fase?

---

## Técnicas de extracción cuando las respuestas son vagas

### Si el usuario dice "como siempre" o "igual que antes"
Preguntar: "¿Puedes confirmar qué patrón específico seguimos? Quiero asegurarme
de documentarlo correctamente en el CONTEXTO.md."

### Si el usuario dice "lo que tú veas mejor"
Registrar como ABIERTA y anotar la decisión que tomará el agente con su
justificación en el CONTEXTO.md.

### Si el usuario da información contradictoria
Señalar la contradicción explícitamente: "Mencionaste X antes pero ahora Y.
¿Cuál aplica para esta fase?"

---

## Plantilla de salida: `.planning/fases/0N-CONTEXTO.md`

```markdown
# CONTEXTO.md — Fase [N]: [Nombre]
**Fecha de discusión**: [fecha]
**Participantes**: [usuario, agente]

## Objetivo de la fase
[Respuesta del usuario a pregunta 1 y 2]

## Criterio de éxito
[Lo que debe existir y funcionar al terminar]

## Restricciones de tiempo
- Deadline: [fecha o "sin deadline definido"]
- Sprint: [número si aplica]

## Decisiones técnicas

| ID  | Decisión | Tipo | Notas |
|-----|---------|------|-------|
| D-01 | [decisión] | CERRADA | [contexto] |
| D-02 | [decisión] | ABIERTA | [el agente decidirá X porque Y] |
| D-03 | [decisión] | PENDIENTE | [bloquea tarea T] |

## Alcance confirmado
### Incluido en esta fase
- Feature A
- Feature B

### Explícitamente excluido
- Feature C (pasa a siguiente fase)

## Dependencias externas
| Dependencia | Equipo/Sistema | Estado | Riesgo |
|------------|---------------|--------|--------|
|            |               |        |        |

## Riesgos identificados
| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|-------------|---------|-----------|
|        |             |         |           |

## Deuda técnica a resolver
- [ ] [deuda 1] — obligatoria
- [ ] [deuda 2] — si hay tiempo

## Decisiones pendientes (bloqueos)
- [ ] [decisión] — necesaria antes de [tarea]

## Notas de la discusión
[Contexto adicional, cambios de opinión, razonamiento detrás de decisiones]
```

---

## Gotchas / Errores comunes no obvios

- **Respuesta "como siempre" archivada sin verificar**: el usuario dice "igual que en la fase anterior" y el agente asume que el patrón aplica sin leer el CONTEXTO.md previo. Causa: confianza en el modelo mental sin verificación. Solución: siempre leer el CONTEXTO.md de la fase anterior antes de aceptar la respuesta.
- **Decisiones PENDIENTE que bloquean el plan ignoradas**: el agente avanza a `planear-fase` con ítems de los Bloques 1 o 4 en estado PENDIENTE. Causa: no se aplicó la Regla 3. Solución: verificar explícitamente que ningún ítem crítico quede PENDIENTE antes de cerrar la discusión.
- **CONTEXTO.md escrito sin confirmar criterio de éxito verificable**: el usuario da un objetivo vago ("mejorar rendimiento") y se registra sin cuestionarlo. Causa: el agente no aplica la prueba de observabilidad. Solución: pedir reformulación hasta que el criterio sea binario y observable.
- **Bloque 2 omitido cuando sí aplica**: si la fase incluye nuevas entidades de BD o endpoints pero el agente saltó el Bloque 2 por considerarlo "técnico". Causa: interpretación laxa de "preguntar si aplica". Solución: si hay código nuevo, el Bloque 2 siempre aplica.

## Checklist de cierre de discusión

Antes de pasar a `planear-fase`, verificar:

- [ ] El objetivo de la fase es una oración accionable (no "mejorar el sistema")
- [ ] El criterio de éxito es verificable (observable sin ambigüedad)
- [ ] No hay decisiones PENDIENTE en ítems de los Bloques 1 y 4
- [ ] Todas las decisiones ABIERTA tienen una nota de qué decidirá el agente
- [ ] Las features excluidas están documentadas explícitamente
- [ ] CONTEXTO.md guardado en `.planning/fases/`
