@saulwade/swl-ses 2.2.0 → 2.2.3

package/comandos/swl/adoptar-proyecto.md

@@ -1,258 +1,253 @@
----
-name: swl:adoptar-proyecto
-description: Incorpora un proyecto existente al sistema SWL. Analiza automáticamente el codebase (stack, arquitectura, dependencias, estado git) y combina los hallazgos con una entrevista corta al usuario para generar los 9 archivos de .planning/ con información real del proyecto — no plantillas vacías.
-allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
-evolved: true
-evolved-from: "1.6.8"
-evolved-at: "2026-05-22"
-evolved-by: "aprender"
-evolved-note: "Paso 8 — validación síncrona del auditor tras modificar CLAUDE.md (contrato cruzado con /swl:claudemd)"
----
-
-# /swl:adoptar-proyecto — Incorporar un proyecto existente al sistema SWL
-
-Eres el coordinador de adopción de proyectos existentes. Tu misión es convertir un codebase que ya existe en un proyecto SWL completamente documentado, combinando análisis automático del código con preguntas específicas al usuario para lo que no se puede inferir.
-
-**Diferencia con `/swl:nuevo-proyecto`**: ese comando parte de cero con entrevista larga. Este comando parte de un codebase existente — primero analiza lo que hay, luego solo pregunta lo que falta.
-
-## Cuándo usar este comando
-
-- Al incorporar un proyecto existente al sistema SWL
-- Cuando un proyecto ya tiene código pero no tiene `.planning/`
-- Cuando se heredó un proyecto y se quiere estructurar con SWL
-- Cuando `swl-ses init` ya creó las plantillas vacías y se necesita poblarlas con datos reales
-
-## Prerrequisitos
-
-1. **SWL instalado** — `swl-ses install` ya ejecutado (global o local)
-2. **Codebase existente** — el proyecto debe tener código fuente (no un directorio vacío — para eso usar `/swl:nuevo-proyecto`)
-3. **Git inicializado** — se usa para detectar estado, ramas y actividad reciente
-
-## Paso 0 — Verificar entorno
-
-1. Confirmar directorio de trabajo actual.
-2. Verificar que es un repositorio git (`git rev-parse --show-toplevel`).
-3. Si no existe `.planning/`, crearlo junto con `.planning/research/`.
-4. Si ya existen archivos en `.planning/` con contenido real (no plantillas), preguntar:
-   ```
-   Ya existe .planning/ con contenido que parece haber sido editado.
-   ¿Deseas sobrescribirlo o solo llenar los archivos que aún son plantillas vacías?
-   ```
-5. Leer `CLAUDE.md` y `README.md` si existen — dan contexto rápido.
-
-### Detección de plantillas vacías vs contenido real
-
-Un archivo es "plantilla vacía" si contiene los marcadores originales de las plantillas SWL:
-- `[Nombre del Proyecto]` o `[Nombre del proyecto]`
-- `YYYY-MM-DD` (más de 2 ocurrencias)
-- `[ej.` (ejemplos no reemplazados)
-- Tablas con todas las celdas vacías (`| | | |`)
-
-Un archivo con estos marcadores se sobrescribe. Un archivo sin ellos se preserva.
-
-## Paso 1 — Análisis automático del codebase
-
-Ejecutar `/swl:mapear-codebase` internamente. Este comando genera:
-- `.planning/research/ARQUITECTURA.md` — análisis completo de la arquitectura
-- `.planning/research/STACK.md` — evaluación del stack tecnológico detectado
-- `.planning/research/TRAMPAS.md` — anti-patrones y deuda técnica encontrada
-
-Capturar los hallazgos clave para usarlos en los pasos siguientes:
-- **Nombre del proyecto**: de `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, o nombre del directorio raíz
-- **Descripción**: de `README.md` (primer párrafo) o del campo `description` del manifiesto
-- **Stack**: lenguajes, frameworks, bases de datos detectados
-- **Estructura**: módulos principales y sus responsabilidades
-- **Dependencias**: lista clasificada del manifiesto
-- **Estado git**: rama actual, último commit, ramas activas, tags existentes
-- **Puntos de entrada**: archivos main/index/app detectados
-- **Deuda técnica**: TODOs, FIXMEs, archivos grandes, dependencias desactualizadas
-
-## Paso 2 — Entrevista corta (solo lo que no se puede inferir)
-
-Presentar al usuario un resumen de lo detectado y hacer SOLO las preguntas que el análisis no puede responder. Agrupar en un solo bloque:
-
-```
-He analizado tu proyecto. Esto es lo que detecté:
-
-  Nombre:        [detectado]
-  Descripción:   [detectada]
-  Stack:         [detectado]
-  Módulos:       [N] módulos principales detectados
-  Dependencias:  [N] de producción, [N] de desarrollo
-  Estado git:    rama [nombre], [N] commits, último hace [tiempo]
-
-Para completar la documentación necesito que me confirmes o ajustes:
-
-1. ¿La descripción de arriba es correcta? Si no, ¿cuál es la descripción correcta del proyecto?
-2. ¿Quiénes son los usuarios finales? (internos, clientes, público)
-3. ¿Hay una fecha límite o hito próximo importante?
-4. ¿Cuál es la prioridad actual? (nueva feature, estabilización, refactor, migración)
-5. ¿Hay algo roto o urgente que deba reflejarse como riesgo activo?
-```
-
-ESPERAR respuesta antes de continuar. No inventar respuestas.
-
-## Paso 3 — Generar `.planning/PROYECTO.md`
-
-Combinar los datos detectados con las respuestas del usuario:
-
-- **Visión**: de la descripción confirmada por el usuario
-- **Stack tecnológico**: tabla auto-llenada desde el análisis de dependencias
-- **Restricciones técnicas**: inferidas del stack (versiones pinneadas, runtime requerido)
-- **Restricciones de negocio**: de la respuesta sobre fechas y prioridades
-- **Objetivos**: derivados de la prioridad actual indicada por el usuario
-- **No-objetivos**: dejar la sección con nota "Definir con `/swl:discutir-fase`"
-- **Equipo**: detectar del git log (contribuidores recientes) + preguntar si aplica
-
-Para la sección de equipo, inferir desde git:
-```bash
-git shortlog -sne --since="6 months ago" | head -10
-```
-
-## Paso 4 — Generar `.planning/ESTADO.md`
-
-Auto-llenar completamente desde el estado actual del repositorio:
-
-- **Fase activa**: "Adopción inicial — incorporación al sistema SWL"
-- **Progreso**: basado en si hay tests, CI, docs
-- **Lo hecho en la última sesión**: "Proyecto adoptado por SWL. Análisis inicial completado."
-- **Decisiones tomadas**: tabla vacía (se llenará conforme se trabaje)
-- **Riesgos activos**: de la deuda técnica detectada + lo que reportó el usuario
-- **Métricas actuales**: cobertura de tests (si se detecta), linter status, dependencias outdated
-- **Bloqueantes**: lo reportado por el usuario como urgente
-- **Próximos pasos**: sugerir `/swl:discutir-fase 1` como siguiente acción
-
-## Paso 5 — Generar `.planning/HOJA-RUTA.md`
-
-Crear un roadmap inicial basado en el estado del proyecto:
-
-- **Fase 0** (completada): "Adopción SWL — análisis del codebase"
-- **Fase 1** (pendiente): Basada en la prioridad indicada por el usuario:
-  - Si "nueva feature" → "Implementación de [feature descrita]"
-  - Si "estabilización" → "Estabilización — tests, CI, docs"
-  - Si "refactor" → "Refactorización de [área detectada con más deuda]"
-  - Si "migración" → "Migración de [tecnología origen] a [destino]"
-- **Fases 2-3**: Marcar como "Por definir con `/swl:discutir-fase`"
-
-## Paso 6 — Generar `.planning/REQUISITOS.md`
-
-Crear una versión inicial con:
-
-- **Requisitos funcionales**: extraer de los endpoints/rutas detectados, agrupados por módulo
-  - Listar cada endpoint o funcionalidad detectable como REQ-NNN en estado "Completado" (ya existe)
-  - Esto da visibilidad de lo que el sistema YA hace
-- **Requisitos no funcionales**: parcialmente inferibles:
-  - Performance: si hay benchmarks o métricas configuradas
-  - Seguridad: si hay auth configurada (JWT, OAuth, etc.)
-  - Tests: cobertura actual como baseline
-- **Nota**: "Los requisitos de nuevas funcionalidades se definen con `/swl:discutir-fase`"
-
-## Paso 7 — Generar archivos de research restantes
-
-### `.planning/research/FUNCIONALIDADES.md`
-
-Listar las funcionalidades detectadas en el codebase:
-- Por cada endpoint/ruta encontrada: método, path, descripción inferida
-- Por cada modelo/entidad: nombre, campos principales
-- Por cada job/worker: nombre, propósito detectado
-
-### `.planning/research/RESUMEN.md`
-
-Consolidar el resumen ejecutivo:
-- TL;DR del proyecto (3-5 bullets)
-- Stack confirmado con versiones
-- Estado actual: qué funciona, qué falta
-- Riesgos principales
-- Recomendación de próximos pasos
-
-### `.planning/research/TRAMPAS.md`
-
-Si `/swl:mapear-codebase` ya lo generó (opción B), solo verificar. Si no:
-- TODOs y FIXMEs agrupados por módulo
-- Anti-patrones detectados en el stack (N+1, eval, shell=True, etc.)
-- Dependencias con CVEs conocidos (si `pip-audit` o `npm audit` están disponibles)
-- Archivos con más de 500 líneas
-
-## Paso 8 — Verificar/actualizar CLAUDE.md del proyecto
-
-Verificar el estado de `CLAUDE.md` en la raíz del proyecto:
-
-- **Si NO existe**: generarlo con la estructura mínima de `/swl:claudemd init-project`.
-  **OBLIGATORIO** incluir como primera sección bajo el título:
-  ```markdown
-  ## Reglas obligatorias
-
-  Aplica la regla global `usar-sistema-swl.md` (matriz operacional del sistema
-  SWL), auto-cargada desde `.claude/rules/`. NO duplicar su contenido aquí.
-  ```
-- **Si existe pero NO menciona la regla global `usar-sistema-swl`**: agregar la
-  mención en una sección "Reglas obligatorias" cerca del inicio del archivo,
-  preservando el contenido existente. NUNCA usar `@reglas/usar-sistema-swl.md`
-  — esa ruta no existe en proyectos downstream (las reglas viven en
-  `.claude/rules/`).
-- **Si existe e incluye la mención**: no tocar.
-
-Esta mención recuerda la matriz operacional del sistema SWL y es el contrato
-base de uso del sistema para el proyecto adoptado.
-
-### Validación síncrona post-modificación (contrato cruzado con /swl:claudemd)
-
-Tras generar o modificar `CLAUDE.md` en este paso, ejecutar el auditor
-síncrono para verificar que respeta el contrato canónico:
-
-```bash
-swl-ses audit-claudemd --json
-# Fallback si el script no está en el proyecto destino:
-npx -y @saulwade/swl-ses@latest audit-claudemd --json
-```
-
-Evaluar `veredicto`:
-
-- `OK` → continuar al Paso 9.
-- `WARN tamano-total` → el CLAUDE.md preexistente más la modificación
-  excedió el umbral. Reportar al usuario y proponer extracción a
-  `@docs/lessons-<tema>.md` antes de cerrar.
-- `WARN bullet-gigante` → revisar y condensar el bullet detectado.
-- `WARN` otras reglas → reportar al usuario pero permitir continuar.
-- `ERROR placeholders` → **DETENER**, revertir la modificación y reportar.
-
-Detalle del contrato cruzado en `@docs/contrato-aprender-claudemd.md`.
-
-## Paso 9 — Reporte final
-
-```
-=== Proyecto adoptado exitosamente ===
-
-Archivos generados:
-  ✓ .planning/PROYECTO.md          — [N] secciones con datos reales
-  ✓ .planning/ESTADO.md            — estado actual del repositorio
-  ✓ .planning/HOJA-RUTA.md         — roadmap inicial con [N] fases
-  ✓ .planning/REQUISITOS.md        — [N] requisitos existentes documentados
-  ✓ .planning/research/ARQUITECTURA.md  — análisis completo del codebase
-  ✓ .planning/research/STACK.md         — evaluación del stack tecnológico
-  ✓ .planning/research/FUNCIONALIDADES.md — inventario de funcionalidades
-  ✓ .planning/research/RESUMEN.md       — resumen ejecutivo consolidado
-  ✓ .planning/research/TRAMPAS.md       — deuda técnica y anti-patrones
-  ✓ CLAUDE.md                          — creado o actualizado con mención de la regla global usar-sistema-swl
-
-Hallazgos clave:
-  1. [hallazgo más importante]
-  2. [segundo hallazgo]
-  3. [tercer hallazgo]
-
-Riesgo principal: [descripción]
-
-Próximo paso recomendado:
-  /swl:discutir-fase 1    ← para definir la primera fase de trabajo
-```
-
-## Reglas de comportamiento
-
-- NUNCA inventar información que no se detectó ni el usuario proporcionó. Si un campo no se puede inferir, dejarlo con nota "Pendiente — definir con `/swl:discutir-fase`".
-- NUNCA modificar archivos de código fuente — solo generar documentación en `.planning/`.
-- Si el proyecto tiene menos de 5 archivos de código, sugerir `/swl:nuevo-proyecto` en su lugar.
-- Si `.planning/` tiene archivos con contenido real, preservarlos y solo llenar los vacíos.
-- La entrevista DEBE ser corta (5 preguntas máximo). Lo que se puede inferir del código, se infiere.
-- Los archivos generados deben ser útiles INMEDIATAMENTE — no plantillas con placeholders.
-- Si un análisis falla (ej: no hay tests, no hay CI), documentar la ausencia como hallazgo, no como error.
-- Preferir exactitud sobre completitud: es mejor un archivo con 3 secciones correctas que uno con 10 secciones adivinadas.
+---
+name: swl:adoptar-proyecto
+description: Incorpora un proyecto existente al sistema SWL. Analiza automáticamente el codebase (stack, arquitectura, dependencias, estado git) y combina los hallazgos con una entrevista corta al usuario para generar los 9 archivos de .planning/ con información real del proyecto — no plantillas vacías.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
+---
+
+# /swl:adoptar-proyecto — Incorporar un proyecto existente al sistema SWL
+
+Eres el coordinador de adopción de proyectos existentes. Tu misión es convertir un codebase que ya existe en un proyecto SWL completamente documentado, combinando análisis automático del código con preguntas específicas al usuario para lo que no se puede inferir.
+
+**Diferencia con `/swl:nuevo-proyecto`**: ese comando parte de cero con entrevista larga. Este comando parte de un codebase existente — primero analiza lo que hay, luego solo pregunta lo que falta.
+
+## Cuándo usar este comando
+
+- Al incorporar un proyecto existente al sistema SWL
+- Cuando un proyecto ya tiene código pero no tiene `.planning/`
+- Cuando se heredó un proyecto y se quiere estructurar con SWL
+- Cuando `swl-ses init` ya creó las plantillas vacías y se necesita poblarlas con datos reales
+
+## Prerrequisitos
+
+1. **SWL instalado** — `swl-ses install` ya ejecutado (global o local)
+2. **Codebase existente** — el proyecto debe tener código fuente (no un directorio vacío — para eso usar `/swl:nuevo-proyecto`)
+3. **Git inicializado** — se usa para detectar estado, ramas y actividad reciente
+
+## Paso 0 — Verificar entorno
+
+1. Confirmar directorio de trabajo actual.
+2. Verificar que es un repositorio git (`git rev-parse --show-toplevel`).
+3. Si no existe `.planning/`, crearlo junto con `.planning/research/`.
+4. Si ya existen archivos en `.planning/` con contenido real (no plantillas), preguntar:
+   ```
+   Ya existe .planning/ con contenido que parece haber sido editado.
+   ¿Deseas sobrescribirlo o solo llenar los archivos que aún son plantillas vacías?
+   ```
+5. Leer `CLAUDE.md` y `README.md` si existen — dan contexto rápido.
+
+### Detección de plantillas vacías vs contenido real
+
+Un archivo es "plantilla vacía" si contiene los marcadores originales de las plantillas SWL:
+- `[Nombre del Proyecto]` o `[Nombre del proyecto]`
+- `YYYY-MM-DD` (más de 2 ocurrencias)
+- `[ej.` (ejemplos no reemplazados)
+- Tablas con todas las celdas vacías (`| | | |`)
+
+Un archivo con estos marcadores se sobrescribe. Un archivo sin ellos se preserva.
+
+## Paso 1 — Análisis automático del codebase
+
+Ejecutar `/swl:mapear-codebase` internamente. Este comando genera:
+- `.planning/research/ARQUITECTURA.md` — análisis completo de la arquitectura
+- `.planning/research/STACK.md` — evaluación del stack tecnológico detectado
+- `.planning/research/TRAMPAS.md` — anti-patrones y deuda técnica encontrada
+
+Capturar los hallazgos clave para usarlos en los pasos siguientes:
+- **Nombre del proyecto**: de `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, o nombre del directorio raíz
+- **Descripción**: de `README.md` (primer párrafo) o del campo `description` del manifiesto
+- **Stack**: lenguajes, frameworks, bases de datos detectados
+- **Estructura**: módulos principales y sus responsabilidades
+- **Dependencias**: lista clasificada del manifiesto
+- **Estado git**: rama actual, último commit, ramas activas, tags existentes
+- **Puntos de entrada**: archivos main/index/app detectados
+- **Deuda técnica**: TODOs, FIXMEs, archivos grandes, dependencias desactualizadas
+
+## Paso 2 — Entrevista corta (solo lo que no se puede inferir)
+
+Presentar al usuario un resumen de lo detectado y hacer SOLO las preguntas que el análisis no puede responder. Agrupar en un solo bloque:
+
+```
+He analizado tu proyecto. Esto es lo que detecté:
+
+  Nombre:        [detectado]
+  Descripción:   [detectada]
+  Stack:         [detectado]
+  Módulos:       [N] módulos principales detectados
+  Dependencias:  [N] de producción, [N] de desarrollo
+  Estado git:    rama [nombre], [N] commits, último hace [tiempo]
+
+Para completar la documentación necesito que me confirmes o ajustes:
+
+1. ¿La descripción de arriba es correcta? Si no, ¿cuál es la descripción correcta del proyecto?
+2. ¿Quiénes son los usuarios finales? (internos, clientes, público)
+3. ¿Hay una fecha límite o hito próximo importante?
+4. ¿Cuál es la prioridad actual? (nueva feature, estabilización, refactor, migración)
+5. ¿Hay algo roto o urgente que deba reflejarse como riesgo activo?
+```
+
+ESPERAR respuesta antes de continuar. No inventar respuestas.
+
+## Paso 3 — Generar `.planning/PROYECTO.md`
+
+Combinar los datos detectados con las respuestas del usuario:
+
+- **Visión**: de la descripción confirmada por el usuario
+- **Stack tecnológico**: tabla auto-llenada desde el análisis de dependencias
+- **Restricciones técnicas**: inferidas del stack (versiones pinneadas, runtime requerido)
+- **Restricciones de negocio**: de la respuesta sobre fechas y prioridades
+- **Objetivos**: derivados de la prioridad actual indicada por el usuario
+- **No-objetivos**: dejar la sección con nota "Definir con `/swl:discutir-fase`"
+- **Equipo**: detectar del git log (contribuidores recientes) + preguntar si aplica
+
+Para la sección de equipo, inferir desde git:
+```bash
+git shortlog -sne --since="6 months ago" | head -10
+```
+
+## Paso 4 — Generar `.planning/ESTADO.md`
+
+Auto-llenar completamente desde el estado actual del repositorio:
+
+- **Fase activa**: "Adopción inicial — incorporación al sistema SWL"
+- **Progreso**: basado en si hay tests, CI, docs
+- **Lo hecho en la última sesión**: "Proyecto adoptado por SWL. Análisis inicial completado."
+- **Decisiones tomadas**: tabla vacía (se llenará conforme se trabaje)
+- **Riesgos activos**: de la deuda técnica detectada + lo que reportó el usuario
+- **Métricas actuales**: cobertura de tests (si se detecta), linter status, dependencias outdated
+- **Bloqueantes**: lo reportado por el usuario como urgente
+- **Próximos pasos**: sugerir `/swl:discutir-fase 1` como siguiente acción
+
+## Paso 5 — Generar `.planning/HOJA-RUTA.md`
+
+Crear un roadmap inicial basado en el estado del proyecto:
+
+- **Fase 0** (completada): "Adopción SWL — análisis del codebase"
+- **Fase 1** (pendiente): Basada en la prioridad indicada por el usuario:
+  - Si "nueva feature" → "Implementación de [feature descrita]"
+  - Si "estabilización" → "Estabilización — tests, CI, docs"
+  - Si "refactor" → "Refactorización de [área detectada con más deuda]"
+  - Si "migración" → "Migración de [tecnología origen] a [destino]"
+- **Fases 2-3**: Marcar como "Por definir con `/swl:discutir-fase`"
+
+## Paso 6 — Generar `.planning/REQUISITOS.md`
+
+Crear una versión inicial con:
+
+- **Requisitos funcionales**: extraer de los endpoints/rutas detectados, agrupados por módulo
+  - Listar cada endpoint o funcionalidad detectable como REQ-NNN en estado "Completado" (ya existe)
+  - Esto da visibilidad de lo que el sistema YA hace
+- **Requisitos no funcionales**: parcialmente inferibles:
+  - Performance: si hay benchmarks o métricas configuradas
+  - Seguridad: si hay auth configurada (JWT, OAuth, etc.)
+  - Tests: cobertura actual como baseline
+- **Nota**: "Los requisitos de nuevas funcionalidades se definen con `/swl:discutir-fase`"
+
+## Paso 7 — Generar archivos de research restantes
+
+### `.planning/research/FUNCIONALIDADES.md`
+
+Listar las funcionalidades detectadas en el codebase:
+- Por cada endpoint/ruta encontrada: método, path, descripción inferida
+- Por cada modelo/entidad: nombre, campos principales
+- Por cada job/worker: nombre, propósito detectado
+
+### `.planning/research/RESUMEN.md`
+
+Consolidar el resumen ejecutivo:
+- TL;DR del proyecto (3-5 bullets)
+- Stack confirmado con versiones
+- Estado actual: qué funciona, qué falta
+- Riesgos principales
+- Recomendación de próximos pasos
+
+### `.planning/research/TRAMPAS.md`
+
+Si `/swl:mapear-codebase` ya lo generó (opción B), solo verificar. Si no:
+- TODOs y FIXMEs agrupados por módulo
+- Anti-patrones detectados en el stack (N+1, eval, shell=True, etc.)
+- Dependencias con CVEs conocidos (si `pip-audit` o `npm audit` están disponibles)
+- Archivos con más de 500 líneas
+
+## Paso 8 — Verificar/actualizar CLAUDE.md del proyecto
+
+Verificar el estado de `CLAUDE.md` en la raíz del proyecto:
+
+- **Si NO existe**: generarlo con la estructura mínima de `/swl:claudemd init-project`.
+  **OBLIGATORIO** incluir como primera sección bajo el título:
+  ```markdown
+  ## Reglas obligatorias
+
+  Aplica la regla global `usar-sistema-swl.md` (matriz operacional del sistema
+  SWL), auto-cargada desde `.claude/rules/`. NO duplicar su contenido aquí.
+  ```
+- **Si existe pero NO menciona la regla global `usar-sistema-swl`**: agregar la
+  mención en una sección "Reglas obligatorias" cerca del inicio del archivo,
+  preservando el contenido existente. NUNCA usar `@reglas/usar-sistema-swl.md`
+  — esa ruta no existe en proyectos downstream (las reglas viven en
+  `.claude/rules/`).
+- **Si existe e incluye la mención**: no tocar.
+
+Esta mención recuerda la matriz operacional del sistema SWL y es el contrato
+base de uso del sistema para el proyecto adoptado.
+
+### Validación síncrona post-modificación (contrato cruzado con /swl:claudemd)
+
+Tras generar o modificar `CLAUDE.md` en este paso, ejecutar el auditor
+síncrono para verificar que respeta el contrato canónico:
+
+```bash
+swl-ses audit-claudemd --json
+# Fallback si el script no está en el proyecto destino:
+npx -y @saulwade/swl-ses@latest audit-claudemd --json
+```
+
+Evaluar `veredicto`:
+
+- `OK` → continuar al Paso 9.
+- `WARN tamano-total` → el CLAUDE.md preexistente más la modificación
+  excedió el umbral. Reportar al usuario y proponer extracción a
+  `@docs/lessons-<tema>.md` antes de cerrar.
+- `WARN bullet-gigante` → revisar y condensar el bullet detectado.
+- `WARN` otras reglas → reportar al usuario pero permitir continuar.
+- `ERROR placeholders` → **DETENER**, revertir la modificación y reportar.
+
+Detalle del contrato cruzado en `@docs/contrato-aprender-claudemd.md`.
+
+## Paso 9 — Reporte final
+
+```
+=== Proyecto adoptado exitosamente ===
+
+Archivos generados:
+  ✓ .planning/PROYECTO.md          — [N] secciones con datos reales
+  ✓ .planning/ESTADO.md            — estado actual del repositorio
+  ✓ .planning/HOJA-RUTA.md         — roadmap inicial con [N] fases
+  ✓ .planning/REQUISITOS.md        — [N] requisitos existentes documentados
+  ✓ .planning/research/ARQUITECTURA.md  — análisis completo del codebase
+  ✓ .planning/research/STACK.md         — evaluación del stack tecnológico
+  ✓ .planning/research/FUNCIONALIDADES.md — inventario de funcionalidades
+  ✓ .planning/research/RESUMEN.md       — resumen ejecutivo consolidado
+  ✓ .planning/research/TRAMPAS.md       — deuda técnica y anti-patrones
+  ✓ CLAUDE.md                          — creado o actualizado con mención de la regla global usar-sistema-swl
+
+Hallazgos clave:
+  1. [hallazgo más importante]
+  2. [segundo hallazgo]
+  3. [tercer hallazgo]
+
+Riesgo principal: [descripción]
+
+Próximo paso recomendado:
+  /swl:discutir-fase 1    ← para definir la primera fase de trabajo
+```
+
+## Reglas de comportamiento
+
+- NUNCA inventar información que no se detectó ni el usuario proporcionó. Si un campo no se puede inferir, dejarlo con nota "Pendiente — definir con `/swl:discutir-fase`".
+- NUNCA modificar archivos de código fuente — solo generar documentación en `.planning/`.
+- Si el proyecto tiene menos de 5 archivos de código, sugerir `/swl:nuevo-proyecto` en su lugar.
+- Si `.planning/` tiene archivos con contenido real, preservarlos y solo llenar los vacíos.
+- La entrevista DEBE ser corta (5 preguntas máximo). Lo que se puede inferir del código, se infiere.
+- Los archivos generados deben ser útiles INMEDIATAMENTE — no plantillas con placeholders.
+- Si un análisis falla (ej: no hay tests, no hay CI), documentar la ausencia como hallazgo, no como error.
+- Preferir exactitud sobre completitud: es mejor un archivo con 3 secciones correctas que uno con 10 secciones adivinadas.