docs
Propósito
Administrador del ciclo de vida de la documentación. Genera documentación inicial del proyecto, mantiene la documentación sincronizada con los cambios en el código, produce referencias de API y genera registros de cambios automáticamente. Resuelve el problema número uno de la documentación: documentos que existen pero están desactualizados.
Disparadores
- Llamado por
scaffoldFase 7 para la generación inicial de documentación - Llamado por
cookdespués de la Fase 7 para actualizar la documentación después de la implementación de funciones - Llamado por
launchantes del despliegue para asegurar que la documentación esté actualizada /rune docs init— generación de documentación por primera vez/rune docs update— sincronizar la documentación con cambios recientes en el código/rune docs api— generar documentación de API/rune docs changelog— generar registro de cambios automáticamente desde el historial de git
Llamadas (salientes)
scout(L2): escanear el código base en busca de objetivos de documentación (rutas, exportaciones, componentes, configuraciones)doc-processor(L3): generar exportaciones PDF/DOCX si se solicitagit(L3): leer el historial de confirmaciones para la generación del registro de cambios
Llamado por (entrantes)
scaffold(L1): Fase 7 — generar documentación inicial para un nuevo proyectocook(L1): después de la implementación — actualizar la documentación para módulos cambiadoslaunch(L1): antes del despliegue — verificar que la documentación esté actualizadamcp-builder(L2): generar documentación del servidor MCP- Usuario: invocación directa
/rune docs
Modos
Modo Inicio — /rune docs init
Generación de documentación por primera vez para un proyecto.
Modo Actualización — /rune docs update
Sincronización incremental — actualizar solo la documentación afectada por cambios recientes en el código.
Modo API — /rune docs api
Generar o actualizar documentación de API específicamente.
Modo Registro de cambios — /rune docs changelog
Generar automáticamente el registro de cambios a partir del historial de confirmaciones de git.
Pasos Ejecutables
Modo Inicio
Paso 1 — Escanear el código base
Invocar rune:scout para extraer:
- Nombre del proyecto, descripción, pila tecnológica
- Estructura de directorios y archivos clave
- Puntos de entrada (main, index, app)
- Superficie de API pública (exportaciones, rutas, componentes)
- Archivos de configuración (.env.example, patrones de configuración)
- Documentación existente (si la hay — fusionar, no sobrescribir)
Paso 2 — Generar README.md
Estructura:
# [Nombre del Proyecto]
[Descripción de una línea]
## Inicio Rápido
[3-5 comandos para empezar: instalar, configurar, iniciar]
## Características
[Lista con viñetas extraída del código — rutas, componentes, capacidades]
## Pila Tecnológica
[Detectada desde package.json, requirements.txt, Cargo.toml, etc.]
## Estructura del Proyecto
[Directorios clave con descripciones de una línea]
## Configuración
[Variables de entorno de .env.example con descripciones]
## Desarrollo
[Comandos de servidor de desarrollo, pruebas, lint, compilación]
## Referencia de API
[Enlace a API.md si corresponde, o resumen en línea]
## Licencia
[Detectada desde el archivo LICENSE o package.json]
Paso 3 — Generar ARCHITECTURE.md (si el proyecto tiene 10+ archivos)
Estructura:
# Arquitectura
## Resumen
[Diagrama del sistema en texto/mermaid — componentes y flujo de datos]
> El resumen de ARQUITECTURA puede llamar a `rune:diagram` para una figura de sistema diseñada (tipo `architecture`) en lugar de Mermaid sin procesar — `suggested_next: diagram`.
## Decisiones Clave
[Patrones detectados: elección de framework, gestión de estado, BD, enfoque de autenticación]
## Mapa de Módulos
[Cada directorio de nivel superior: propósito, archivos clave, dependencias]
## Flujo de Datos
[Descripción del ciclo de vida de la solicitud o tubería de datos]
Paso 4 — Generar API.md (si se detectan rutas/endpoints)
Escanear archivos de ruta y extraer:
- Método HTTP + ruta
- Parámetros de solicitud (ruta, consulta, cuerpo)
- Forma de la respuesta
- Requisitos de autenticación
- Respuestas de error
Formatear como tabla de markdown o referencia compatible con OpenAPI.
Paso 5 — Informar
Presentar la documentación generada al usuario con un resumen:
- Archivos generados: [lista]
- Cobertura: [qué está documentado vs qué existe]
- Brechas: [áreas de código sin documentación — sugerir próximos pasos]
Modo Actualización
Paso 1 — Detectar cambios
Leer git diff desde la última actualización de documentación (rastreado mediante el registro de git en archivos de documentación o .rune/docs-sync.json).
Identificar:
- Nuevos archivos/módulos → necesitan nuevas secciones de documentación
- Funciones/rutas cambiadas → necesitan actualizaciones de documentación
- Código eliminado → necesita eliminación de documentación
- Nueva configuración → necesita actualización de documentación de configuración
Paso 2 — Actualizar secciones afectadas
Para cada área cambiada:
- Leer el código cambiado
- Encontrar la sección de documentación correspondiente
- Actualizar la documentación para que coincida con el código actual
- Si la sección de documentación no existe → crearla
- Si el código fue eliminado → eliminar o marcar como obsoleto en la documentación
Paso 3 — Generar entrada de registro de cambios
Delegar en rune:git changelog para producir una entrada de registro de cambios a partir de las confirmaciones desde la última actualización de la documentación.
Paso 4 — Pasada de consistencia entre documentos
La consistencia entre documentos evita el segundo problema más común de la documentación: documentos que existen pero se contradicen entre sí.
Después de actualizar cualquier documento, verificar la consistencia en toda la documentación del proyecto:
| Verificación | Archivos | Qué Comparar |
|---|---|---|
| Números de versión | README, CLAUDE.md, package.json, CHANGELOG | Todos deben coincidir con la versión actual |
| Listas de características | README, página de inicio, CLAUDE.md | Mismas características listadas (pueden diferir en nivel de detalle) |
| Estadísticas | README, CLAUDE.md, página de inicio, panel | El conteo de habilidades, pruebas, señales debe coincidir |
| Comandos | README, CLAUDE.md, docs/ | Mismos comandos con las mismas banderas |
| Pila tecnológica | README, ARCHITECTURE.md, CLAUDE.md | Referencias consistentes a frameworks/bibliotecas |
Consistencia entre documentos:
- [x] README.md ↔ CLAUDE.md: versiones coinciden, comandos coinciden
- [x] README.md ↔ docs/index.html: estadísticas coinciden, características coinciden
- [ ] README.md dice "62 habilidades" pero CLAUDE.md dice "59" → CORREGIR CLAUDE.md
Corregir inconsistencias inmediatamente — no solo informarlas. Actualizar el documento desactualizado para que coincida con la fuente de verdad (generalmente el código o el documento más recientemente actualizado).
Paso 5 — Informar
Mostrar al usuario: qué se actualizó, qué se agregó, qué se marcó para revisión. Incluir resultados de la Pasada de Consistencia entre Documentos.
Modo API
Paso 1 — Detectar framework de API
| Framework | Patrón de Ruta | Patrón de Archivo |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts, *.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py, main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
Paso 2 — Extraer endpoints
Para cada ruta detectada:
- Método (GET, POST, PUT, DELETE, PATCH)
- Ruta (con parámetros resaltados)
- Solicitud: parámetros, consulta, forma del cuerpo (de esquemas Zod, tipos TypeScript, modelos Pydantic)
- Respuesta: forma (del tipo de retorno o helper de respuesta)
- Autenticación: ¿requerida? (detectar middleware como
authMiddleware,@UseGuards) - Descripción: de JSDoc/docstring si está disponible
Paso 3 — Generar referencia de API
Formatear como markdown:
# Referencia de API
## Autenticación
[Descripción del mecanismo de autenticación]
## Endpoints
### `POST /api/auth/login`
**Descripción**: Autenticar usuario y devolver tokens
**Autenticación**: Ninguna
**Cuerpo de la Solicitud**:
| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| email | string | sí | Correo electrónico del usuario |
| password | string | sí | Contraseña del usuario |
**Respuesta** (200):
```json
{ "token": "string", "refreshToken": "string" }
Errores:
- 401: Credenciales inválidas
- 422: Error de validación
#### Paso 4 — Salida
Guardar en `docs/API.md` o ubicación específica del proyecto. Si se solicita OpenAPI, generar `openapi.yaml`.
### Modo Registro de cambios
#### Paso 1 — Delegar a Git
Invocar `rune:git changelog` para agrupar confirmaciones por tipo y formatear como Keep a Changelog.
#### Paso 2 — Mejorar
Agregar contexto al registro de cambios sin procesar:
- Vincular números de PR a descripciones reales
- Agrupar cambios relacionados bajo encabezados de características
- Resaltar cambios importantes de manera prominente
#### Paso 3 — Salida
Agregar o actualizar `CHANGELOG.md`.
## Formato de Salida
### Salida del Modo Inicio
Archivos generados en la raíz del proyecto:
- `README.md` — Inicio Rápido, Características, Pila Tecnológica, Estructura, Configuración, Comandos de Desarrollo
- `ARCHITECTURE.md` — Diagrama de resumen, Decisiones Clave, Mapa de Módulos, Flujo de Datos (si hay 10+ archivos)
- `docs/API.md` — Referencia de endpoints con método, ruta, parámetros, respuesta, autenticación (si se detectan rutas)
### Salida del Modo Actualización
Secciones de documentación modificadas con resumen de cambios:
Informe de Actualización de Documentación:
- Actualizado: [lista de secciones de documentación modificadas]
- Agregado: [nuevas secciones para código nuevo]
- Marcado: [secciones obsoletas que hacen referencia a código eliminado]
- Registro de cambios: [entrada añadida a CHANGELOG.md]
### Salida del Modo API
`docs/API.md` — referencia markdown por endpoint:
MÉTODO /ruta/:param
Descripción: [de JSDoc/docstring] Autenticación: [requerida/ninguna] Solicitud: [tabla de parámetros, consulta, cuerpo] Respuesta: [forma con códigos de estado] Errores: [códigos de error y descripciones]
### Salida del Modo Registro de cambios
`CHANGELOG.md` — formato Keep a Changelog agrupado por: Añadido, Corregido, Cambiado, Eliminado.
## Restricciones
1. DEBE generar documentación a partir del código real — nunca inventar características o API que no existen
2. DEBE preservar la documentación existente — actualizar secciones, no sobrescribir archivos completos
3. DEBE detectar documentación obsoleta — marcar secciones que hacen referencia a código eliminado/cambiado
4. DEBE incluir Inicio Rápido en cada README — los usuarios deben poder empezar en menos de 2 minutos
5. NO DEBE generar documentación para código que aún no existe (a menos que se estén creando explícitamente documentos de especificación)
6. La documentación de API DEBE coincidir con las firmas reales de las rutas — una documentación de API incorrecta es peor que ninguna
## Retornos
| Artefacto | Formato | Ubicación |
|-----------|--------|-----------|
| README.md | Markdown | raíz del proyecto |
| ARCHITECTURE.md | Markdown | raíz del proyecto (si hay 10+ archivos) |
| Referencia de API | Markdown | `docs/API.md` |
| Entrada de registro de cambios | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| Informe de actualización de documentación | Markdown | en línea (salida del chat) |
**Guardarraíl de alcance:** Documenta solo lo que existe en el código base — nunca inventa características, endpoints o API.
## Bordes Afilados
| Modo de Falla | Gravedad | Mitigación |
|---|---|---|
| Inventar endpoints de API que no existen | CRÍTICA | Restricción 1: escanear archivos de ruta reales, no adivinar |
| Sobrescribir secciones de README escritas por el usuario | ALTA | Restricción 2: fusionar, no sobrescribir — detectar secciones personalizadas |
| Documentación obsoleta después de cambios en el código | ALTA | El modo Actualización detecta diferencias y actualiza las secciones afectadas |
| Documentación de API con formas de solicitud/respuesta incorrectas | ALTA | Extraer de tipos Zod/Pydantic/TypeScript, no de la memoria |
| Falta la sección de Inicio Rápido | MEDIA | Restricción 4: cada README tiene Inicio Rápido |
| Registro de cambios con enlaces a PR huérfanos | BAJA | Validar que los números de PR existan antes de enlazar |
| Inconsistencia entre documentos (README dice X, CLAUDE.md dice Y) | ALTA | Paso 7: Pasada de Consistencia entre Documentos — verificar que las estadísticas, versiones y listas de características coincidan en todos los documentos |
| Actualizar un documento pero no otros (deriva de estadísticas) | ALTA | Después de cualquier actualización de documentación, barrer todos los documentos relacionados para detectar estadísticas obsoletas — especialmente README ↔ CLAUDE.md ↔ página de inicio |
## Hecho Cuando
### Modo Inicio
- Código base escaneado con scout
- README.md generado con Inicio Rápido, Características, Pila Tecnológica, Estructura
- ARCHITECTURE.md generado (si hay 10+ archivos)
- API.md generado (si se detectan rutas)
- Informe de cobertura presentado al usuario
### Modo Actualización
- Cambios desde la última actualización de documentación detectados
- Secciones de documentación afectadas actualizadas
- Entrada de registro de cambios generada
- Informe de actualización presentado al usuario
### Modo API
- Framework de API detectado
- Todos los endpoints extraídos con método, ruta, solicitud, respuesta
- Referencia de API generada en markdown
- Guardada en docs/API.md
### Modo Registro de cambios
- Confirmaciones agrupadas por tipo
- Formateado como Keep a Changelog
- CHANGELOG.md actualizado
## Perfil de Costo
~2000-5000 tokens de entrada, ~1000-3000 tokens de salida. Sonnet — la documentación requiere comprender patrones de código pero no razonamiento arquitectónico profundo.