# Regla: Análisis previo ante tareas grandes

Esta regla es OBLIGATORIA y aplica a todo trabajo donde la solicitud del usuario
implique cambio masivo: porte de sistema, refactor cross-módulo, replicación de
arquitectura externa, migración de stack, instalación de framework completo,
adopción de patrón en N módulos.

---

## Principio

> Cuando el usuario pide "replicar íntegramente X", "portar todo Y", "implementar
> el sistema completo Z", **responde primero con análisis comparativo (qué ya
> existe vs. qué falta) y propón 3 opciones de alcance** (mínima / media /
> completa) antes de escribir código. Nunca arrancar el porte literal sin
> confirmación explícita tras presentar opciones.

---

## Cómo aplicar

### Detección — qué cuenta como "tarea grande"

Cualquier solicitud que tenga al menos uno de estos atributos:

- Más de ~10 archivos a crear, mover o reescribir.
- Más de ~500 LOC estimadas a tocar en un solo turno.
- Toca más de un dominio (backend + frontend, o varios módulos backend).
- "Replicar X" donde X es un sistema externo con su propia arquitectura.
- "Portar todo de Y" donde Y es un repo, framework o lib voluminoso.
- "Implementar todo Z" donde Z es una fase, un sub-sistema, una capa nueva.
- Análisis de un repo en `temp/` con la pregunta abierta "¿qué adoptamos?".

Si la solicitud encaja en cualquiera de estas, aplicar la regla.

### Paso 1 — Auditar lo que ya existe

Antes de proponer el porte:

- `Glob` / `Grep` / `Read` para mapear el código actual del usuario.
- Identificar componentes que ya cubren parte de la solicitud.
- Verificar versiones, dependencias, convenciones del proyecto.
- Si es repo externo en `temp/`: aplicar **filtro de dominio** primero
  (ver `reglas/arquitectura.md` § "Análisis de repositorios externos").
  Descartar 80-95% del contenido vertical antes de análisis profundo.

### Paso 2 — Tabla comparativa

Producir una tabla con tres columnas:

| Componente del sistema externo | Equivalente actual del usuario | Gap |
|---|---|---|
| ... | ya existe / parcial / no existe | qué falta agregar |

Sin la tabla, no se proponen opciones. La tabla es la base objetiva de la decisión.

### Paso 3 — Tres opciones de alcance

Siempre presentar tres opciones:

- **Mínima** — solo cierra los gaps críticos (lo que NO existe). Esfuerzo
  estimado bajo. Usuario acepta vivir con diferencias menores en lo demás.
- **Media** — cierra gaps + alinea componentes parciales con el patrón externo.
  Esfuerzo medio. Convergencia parcial sin reescribir lo que ya funciona.
- **Completa** — porte literal de todo lo que el usuario pidió, sin reusar
  componentes existentes. Esfuerzo alto. Justificable solo cuando la
  arquitectura externa es estrictamente superior.

Cada opción incluye:

- Estimación de esfuerzo (turnos, LOC, archivos afectados).
- Lista de tareas concretas si se elige.
- Riesgos / tradeoffs específicos.

### Paso 4 — Recomendación explícita

Tras las tres opciones, **recomendar una** con razonamiento. No dejar la
decisión "abierta" — el usuario espera tu juicio técnico.

Patrón de recomendación:

> **Recomiendo la opción [N]** porque [razón concreta]. Las opciones [otras]
> son válidas si [condición específica].

### Paso 5 — Esperar confirmación

Después de presentar tabla + opciones + recomendación: detenerse y esperar.

NO arrancar a escribir código asumiendo aprobación implícita. La autorización
debe ser literal del usuario ("procede con la opción 2", "adelante con la
mínima", "hagamos la completa").

---

## Excepciones — cuándo NO aplicar la regla

NO aplicar cuando:

1. **El usuario ya pidió explícitamente la opción**: "implementa la versión
   mínima de X" o "porta solo el módulo Y" — la elección ya está hecha.
2. **El alcance es trivial** — menos de 5 archivos, una sola dependencia.
3. **El usuario pidió análisis y ya decidió**: si ya hubo una sesión previa con
   la tabla comparativa y el usuario eligió, proceder sin re-presentar.
4. **Es un fix urgente de producción** — bug crítico, vulnerabilidad activa,
   incidente. El análisis se reduce a confirmar la causa y aplicar el fix
   específico.

---

## Cómo presentar la tabla y opciones

### Formato de tabla comparativa (mínimo)

```markdown
| Componente | Sistema externo | Tu sistema actual | Gap |
|---|---|---|---|
| Auth | OAuth2 + PKCE | JWT custom | parcial — falta PKCE |
| Storage | S3 + presigned | filesystem local | falta — pendiente migración |
| ... | ... | ... | ... |
```

### Formato de las tres opciones (mínimo)

```markdown
**Opción A — Mínima** (~3 turnos, ~15 archivos)
- Cerrar solo gaps críticos: PKCE, presigned URLs.
- No tocar lo que ya funciona.
- Riesgo: leve divergencia con sistema externo en convenciones menores.

**Opción B — Media** (~6 turnos, ~30 archivos)
- Cerrar gaps + alinear `auth/` con patrón OAuth2 completo.
- Mantener storage actual con migración planeada en fase futura.
- Riesgo: refactor en `auth/` puede romper integraciones existentes.

**Opción C — Completa** (~15 turnos, ~80 archivos)
- Porte literal del sistema externo completo.
- Reemplaza todo lo equivalente, no importa que ya funcione.
- Riesgo: regresiones en funcionalidad madura.

**Recomiendo la Opción A**: el sistema actual cubre el 80% del valor;
los gaps específicos resuelven el caso concreto sin riesgo de regresión.
```

---

## Anti-patrones

- Arrancar a escribir código tras "replícame X" sin tabla comparativa.
- Presentar las opciones sin recomendar — pasar la pelota al usuario.
- Listar 5+ opciones cuando 3 son suficientes (mínima / media / completa).
- Estimar esfuerzo en términos vagos ("bastante trabajo", "no mucho") sin
  cuantificar turnos / archivos / LOC.
- Omitir la auditoría de lo que ya existe y proponer porte literal de todo.
- Cuando el usuario pide la opción mínima, expandir el alcance "porque
  conviene" sin pedir confirmación.

---

## Origen de esta regla

Consolidada el 2026-05-04 desde feedback del usuario en sesión 2026-04-18 sobre
porte de Hermes Agent: tras pedir "replicar íntegramente Hermes Agent" (~960
archivos Python), aceptó la propuesta de cerrar solo 3 gaps específicos
(perfil de usuario, cron natural, auto-evolución). Lección: la auditoría previa
+ opciones explícitas evita re-implementar 80% de funcionalidad ya existente.

Reforzada en análisis de repos en `temp/` durante v1.1.0 de swl-ses (2026-04-23):
filtro de dominio descartó 97% del contenido de 5 repos antes de análisis
profundo, ahorrando horas de trabajo en arquitectura externa irrelevante.

Memoria nativa local correspondiente (`feedback_analisis_previo.md` en swl-ses):
redundante tras esta regla; el contenido operativo vive aquí.
