Cómo usar¶
Activar Reversa¶
Después de instalar, abre el proyecto en tu agente de IA y activa Reversa:
Eso es todo. Reversa toma el control y coordina todo el análisis desde ahí.
Elegir el comando de entrada¶
/reversa es el punto de entrada para analizar un sistema existente, pero no es el único flujo:
| Objetivo | Comando |
|---|---|
| Analizar un legado existente y producir specs | /reversa |
| El mismo análisis, de punta a punta, sin paradas intermedias | /reversa-autonomous |
| Empezar un proyecto nuevo desde una idea en una línea | /reversa-new (con expresso llega hasta el código) |
| Evolucionar el sistema una feature a la vez, de la spec al código | /reversa-forward |
| Implementar una cola de features (ej. features 10 a 20) de punta a punta, sin paradas | /reversa-forward-autonomous |
| Enmendar un ajuste corto en la feature recién entregada | /reversa-add |
| Converger una feature entregada de vuelta en la extracción | /reversa-sync |
| Reconstruir el legado en un stack moderno | /reversa-migrate |
| Mejorar la estructura interna sin cambiar el comportamiento observable | /reversa-refactor |
| Renderizar el conocimiento extraído como mini-sitio HTML | /reversa-docs |
| Registrar y corregir defectos con trazabilidad causal | /reversa-debugger, /reversa-debugger-fix |
| Decidir cómo vender y poner precio al producto o a cada feature | /reversa-pricing |
| Diseñar, criticar, auditar o pulir una interfaz de front-end (Impeccable) | /impeccable |
Modo sin supervisión¶
Si quieres que el análisis corra sin ti frente a la terminal:
Ejecuta exactamente los mismos agentes y fases que /reversa, pero concentra todas las preguntas en una entrevista única al inicio (datos de instalación, nivel de documentación, organización de las specs) y salta lo que ya esté respondido en .reversa/state.json. Tras la entrevista va hasta el final, deteniéndose solo ante la lista cerrada de situaciones que realmente requieren un humano.
La misma idea existe del lado greenfield: /reversa-new expresso "<tu idea>" va de la idea al código implementado sin parar, encadenando con el ciclo forward en cuanto las specs están listas.
Para evolucionar un sistema que ya tiene specs, /reversa-forward-autonomous ejecuta el ciclo forward sobre una cola de features (ej. "features 10 a 20"), de requirements a sync, una tras otra. Es el comando para usar con /goal, por ejemplo /goal ejecuta /reversa-forward-autonomous en las features 10 a 20, usa los valores por defecto. Escribe código del proyecto solo en la fase coding y solo donde .reversa/reversa-config.json lo permita; con la política bloqueada, se detiene antes de empezar.
Hecho para sesiones con aprobación automática
Estos modos son para entornos donde las herramientas se aprueban automáticamente (modo YOLO de Claude Code o equivalente). Como nadie está aprobando cada acción, las barreras son más estrictas: la escritura queda restringida a .reversa/ y las carpetas de salida, y ningún comando destructivo o de efecto externo (borrar, git push, publicar, instalar dependencias) se ejecuta por cuenta propia. Aun así, haz backup del proyecto antes de empezar, como se recomienda en la página inicial. /reversa-forward-autonomous es la excepción: su fase coding edita código del proyecto, solo donde .reversa/reversa-config.json lo permita, y ejecuta los builds, tests e instalaciones que actions.md pida explícitamente.
Qué ocurre al activarlo¶
Reversa verifica si hay un análisis en curso:
Primera vez: crea un plan de exploración personalizado para tu proyecto, lo presenta para aprobación y comienza el análisis en la fase 1.
Sesión retomada: lee el checkpoint guardado en .reversa/state.json y continúa exactamente donde se quedó. No importa si cerraste el editor, reiniciaste la máquina o lo dejaste dormido tres días.
Flujo típico de un análisis completo¶
Escribes /reversa
↓
Reversa crea el plan de exploración
↓
Revisas y apruebas el plan
↓
Scout mapea la superficie del proyecto
↓
Reversa presenta el resumen del Scout y eliges el nivel de documentación
↓
Archaeologist analiza módulo por módulo
↓
Detective y Architect interpretan lo encontrado
↓
Writer genera las especificaciones (una a la vez, con tu aprobación)
↓
Reviewer revisa todo y plantea preguntas de validación
↓
Especificaciones listas en _reversa_sdd/
El proceso es incremental y conversacional. No necesitas estar presente todo el tiempo: Reversa te avisa cuando te necesita.
¿Cuánto tiempo lleva?¶
Depende del tamaño del proyecto, pero una regla general:
| Tamaño del proyecto | Estimado |
|---|---|
| Pequeño (< 10 módulos) | 2 a 4 sesiones |
| Mediano (10 a 30 módulos) | 5 a 10 sesiones |
| Grande (30+ módulos) | 10+ sesiones |
El Archaeologist analiza un módulo por sesión a propósito, para conservar contexto. Para proyectos grandes retomarás varias veces, pero cada retomada es automática y sin pérdida de progreso.
Consejo: desbordamiento de contexto¶
Si la sesión se alarga y el contexto empieza a agotarse, Reversa guarda el checkpoint automáticamente y avisa:
"Voy a pausar aquí. Todo está guardado. Escribe
/reversaen una nueva sesión para continuar."
Sin drama. Sin pérdida. Solo continúa después.
Nivel de documentación¶
Después de que el Scout termina, Reversa presenta un resumen de lo que encontró (cantidad de módulos, integraciones, presencia de base de datos) y pregunta qué volumen de documentación quieres para el proyecto:
| Nivel | Cuándo usar | Qué genera |
|---|---|---|
| Esencial | Proyectos simples, scripts, prototipos | Artefactos principales: análisis de código, dominio, arquitectura, specs SDD |
| Completo | Proyectos medianos, equipos pequeños (por defecto) | Todo lo esencial + diagramas C4, ERD, ADRs, OpenAPI, user stories y matrices de trazabilidad |
| Detallado | Sistemas enterprise, múltiples equipos | Todo lo completo + flowcharts por función, ADRs expandidos, diagrama de deployment y revisión cruzada obligatoria |
La elección se guarda en .reversa/state.json y todos los agentes siguientes la respetan automáticamente. Si necesitas ajustarla después de iniciado el análisis, edita el campo doc_level en ese archivo.
Activar un agente específico manualmente¶
Si quieres ejecutar un agente suelto, sin pasar por el orquestador:
Útil cuando ya tienes un análisis en curso y quieres ejecutar un agente específico por alguna razón puntual.