Generador de guías de incorporación a la wiki

Genera cuatro documentos de incorporación adaptados a cada público en la carpeta «onboarding/», cada uno de los cuales proporciona a un grupo de interés concreto exactamente la información que necesita.

Resolución del repositorio de origen (IMPRESCINDIBLE HACERLO PRIMERO)

Antes de generar ninguna guía, DEBES determinar el contexto del repositorio de origen:

1. Comprueba si hay un git remote: ejecuta el comando «git remote get-url origin» para detectar si existe un remote
2. Pregunta al usuario: «¿Se trata de un repositorio solo local o dispones de una URL de repositorio de origen (por ejemplo, GitHub, Azure DevOps)?»
   • Si se proporciona una URL remota → guárdala como REPO_URL y utiliza citas enlazadas: [archivo:línea](REPO_URL/blob/BRANCH/archivo#Llínea)
   • Solo local → utiliza citas locales: (ruta_del_archivo:número_de_línea)
3. Determina la rama predeterminada: ejecuta «git rev-parse --abbrev-ref HEAD»
4. NO continúes hasta que se haya resuelto el contexto del repositorio de origen

Cuándo activarlo

• El usuario solicita documentación de incorporación o guías de introducción
• El usuario ejecuta el comando /deep-wiki:onboard
• El usuario quiere ayudar a los nuevos miembros del equipo a comprender el código

Estructura de salida

Genera una carpeta «onboarding/» con estos archivos:

onboarding/
├── index.md                    # Centro de incorporación: enlaces a las cuatro guías con descripciones de los destinatarios
├── contributor-guide.md        # Para nuevos colaboradores (se presupone que tienen conocimientos de Python o JS)
├── staff-engineer-guide.md     # Para ingenieros de plantilla e ingenieros principales
├── executive-guide.md          # Para líderes de ingeniería a nivel de vicepresidente o director
└── product-manager-guide.md    # Para gestores de producto y partes interesadas ajenas a la ingeniería

index.md — Centro de incorporación

Una página de inicio con:

• Un resumen del proyecto de un párrafo
• Tabla de selección de guías:

Detección de lenguaje

Analiza el repositorio en busca de archivos de compilación para determinar el lenguaje principal de los ejemplos de código:

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Guía 1: Guía para colaboradores

Archivo: onboarding/contributor-guide.md Destinatarios: Ingenieros que se incorporan al proyecto. Se da por supuesto un dominio de Python o JavaScript y experiencia general en ingeniería de software. Extensión: 1000–2500 líneas. Progresiva: cada sección se basa en la anterior.

Secciones obligatorias

Parte I: Fundamentos (omitir si el repositorio utiliza Python o JS)

1. {Lenguaje principal} para ingenieros de Python/JS: tablas comparativas de sintaxis, modelo asíncrono, colecciones, sistema de tipos y gestión de paquetes. Código concreto en paralelo, NO descripciones abstractas.
2. Fundamentos de {marco principal} — Comparación con marcos equivalentes de Python/JS (p. ej., FastAPI, Express). Flujo de peticiones, enrutamiento, inyección de dependencias, configuración.

Parte II: Este código fuente 3. Qué hace este proyecto — Presentación breve de 2-3 frases 4. Estructura del proyecto — Árbol de directorios comentado (qué hay en cada sitio y por qué). Incluye un gráfico con la visión general de la arquitectura de la base de datos. 5. Conceptos fundamentales — Terminología específica del dominio explicada con ejemplos de código. Utiliza un diagrama ER para el modelo de datos. 6. Ciclo de vida de una solicitud — Diagrama de secuencia (con numeración automática) que traza una solicitud típica de principio a fin. 7. Patrones clave — Plantillas del tipo «Si quieres añadir X, sigue este patrón» con código real

Parte III: Ponerse a trabajar 8. Requisitos previos y configuración — Tabla: herramienta, versión, comando de instalación. Guía paso a paso con el resultado esperado en cada paso. 9. Tu primera tarea — Guía paso a paso para añadir una característica sencilla 10. Flujo de trabajo de desarrollo — Estrategia de ramas, convenciones de commit, proceso de PR. Utiliza diagramas de flujo. 11. Ejecución de pruebas: todas las pruebas, un solo archivo, una sola prueba, comandos de cobertura. 12. Guía de depuración: tabla de problemas comunes: síntoma, causa, solución. 13. Errores habituales: errores que cometen todos los nuevos colaboradores y cómo evitarlos.

Anexos

• Glosario (más de 40 términos)
• Referencia de archivos clave — Tabla: ruta, finalidad, importancia, código fuente
• Ficha de referencia rápida — Hoja de referencia con los comandos y patrones más utilizados

Normas

• Todos los ejemplos de código en el idioma principal detectado
• Cada comando debe poder copiarse y pegarse con el resultado esperado
• Mínimo de 5 diagramas Mermaid (arquitectura, ER, secuencia, diagrama de flujo, estados)
• Utiliza Mermaid para los diagramas de flujo de trabajo (colores de modo oscuro); añade un bloque de comentarios después de cada uno
• Justifica todas las afirmaciones con código real — cita utilizando el formato de enlaces

Guía 2: Guía para ingenieros sénior

Archivo: onboarding/staff-engineer-guide.md Destinatarios: Ingenieros de plantilla/principales que necesitan conocer el «porqué» detrás de cada decisión. Con amplia experiencia en sistemas, es posible que no conozcan el lenguaje de este repositorio. Extensión: 800–1200 líneas. Denso, con opiniones firmes, de carácter arquitectónico.

Secciones obligatorias

1. Resumen ejecutivo: qué es el sistema en un párrafo conciso. Qué gestiona y qué delega.
2. La idea arquitectónica fundamental — El ÚNICO concepto más importante. Incluye pseudocódigo en un lenguaje DIFERENTE al del repositorio.
3. Arquitectura del sistema — Diagrama TB completo en Mermaid. Destaca el «corazón» del sistema.
4. Modelo de dominio: diagrama ER de Mermaid de las entidades principales. Tabla de invariantes de datos: Entidad, Invariable, Aplicado por, Fuente.
5. Abstracciones e interfaces clave: diagrama de clases que muestre las abstracciones que soportan la carga.
6. Ciclo de vida de una solicitud: diagrama de secuencia (con numeración automática) que muestra una solicitud típica desde la entrada hasta la respuesta.
7. Transiciones de estado: diagrama de estado v2 para entidades con estados de ciclo de vida significativos.
8. Registro de decisiones: tabla con los campos «Decisión», «Alternativas consideradas», «Justificación» y «Fuente».
9. Justificación de las dependencias — Tabla: Dependencia, Propósito, A qué sustituye, Fuente.
10. Flujo de datos y estado — Cómo se mueven los datos por el sistema. Tabla comparativa de almacenamiento.
11. Modos de fallo y gestión de errores: diagrama de flujo de las rutas de propagación de errores.
12. Características de rendimiento — Cuellos de botella, límites de escalabilidad, rutas críticas.
13. Modelo de seguridad — Autenticación, autorización, límites de confianza, sensibilidad de los datos.
14. Estrategia de pruebas: qué se prueba, qué no se prueba, filosofía de pruebas.
15. Deuda técnica conocida — Tabla: problema, nivel de riesgo, archivos afectados, fuente.
16. Dónde profundizar — Ordende lectura recomendado de los archivos fuente, enlaces a secciones de la wiki.

Reglas

• Utiliza pseudocódigo en otro lenguaje para explicar conceptos
• Utiliza tablas comparativas para explicar conceptos desconocidos (p. ej., Tarea o = Awaitable[T])
• Texto denso con tablas, NO listas de viñetas superficiales
• Cada afirmación debe ir respaldada por una cita enlazada
• Un mínimo de 5 diagramas Mermaid (de arquitectura, ER, de clases, de secuencia, de estados y de flujo)
• Cada diagrama debe ir seguido de un bloque de comentarios
• Utiliza tablas de forma intensiva: las decisiones, las dependencias y la deuda deben aparecer TODAS en tablas con columnas de «Fuente»
• Céntrate en el PORQUÉ de las decisiones, no solo en lo que existe

Guía 3: Guía para ejecutivos

Archivo: onboarding/executive-guide.md Destinatarios: vicepresidente o director de ingeniería. Necesita una visión general de las capacidades, una evaluación de riesgos y el contexto de la inversión; NO detalles a nivel de código. Extensión: 400-800 líneas. Estratégico, conciso y orientado a la toma de decisiones.

Secciones obligatorias

1. Descripción general del sistema: qué hace, quién lo utiliza y su valor empresarial en 2-3 frases
2. Mapa de capacidades: tabla con capacidad, estado (implementada/parcial/prevista), madurez y dependencias. Lo que el sistema puede y no puede hacer en la actualidad.
3. Resumen de la arquitectura: diagrama LR de alto nivel tipo «Mermaid». Servicios, almacenes de datos, integraciones externas — SIN detalles internos del código. Centrarse en las unidades de implementación y los límites de los equipos.
4. Topología del equipo: qué equipo o persona es responsable de cada componente. Tabla: componente, responsable, criticidad, factor de bus.
5. Tesis de inversión tecnológica — Por qué se eligieron estas tecnologías. Tabla: Tecnología, finalidad, alternativas consideradas, nivel de riesgo.
6. Evaluación de riesgos — Tabla: riesgo, probabilidad, impacto, mitigación, responsable. Abarca la fiabilidad, la seguridad, la escalabilidad y el cumplimiento normativo.
7. Modelo de costes y escalabilidad: cómo varían los costes en función del uso. Cuáles son los cuellos de botella. Cuándo se necesitará la próxima inversión en escalabilidad.
8. Mapa de dependencias: gráfico de TB que muestra las dependencias externas críticas. Tabla: Dependencia, Tipo (servicio/biblioteca/plataforma), riesgo en caso de indisponibilidad.
9. Métricas clave y observabilidad — Qué se mide, qué paneles de control existen, cobertura de alertas. Tabla: Métrica, valor actual, objetivo, fuente.
10. Alineación con la hoja de ruta: flujos de trabajo de ingeniería alineados con las prioridades empresariales. Lo que está en curso, lo que está previsto, lo que está bloqueado.
11. Resumen de la deuda técnica: las 5 principales partidas de deuda con impacto en el negocio. Tabla: problema, impacto en el negocio, esfuerzo necesario para solucionarlo, prioridad.
12. Recomendaciones: de 3 a 5 recomendaciones prácticas para el próximo trimestre, priorizadas por impacto.

Normas

• NO se incluyen fragmentos de código: esta guía está dirigida a responsables de ingeniería, no a programadores
• Diagramas a nivel de servicio o equipo, no a nivel de clase o función
• Cada afirmación debe estar respaldada por pruebas: cita secciones de la wiki, documentos de arquitectura o archivos fuente
• Mínimo de 3 diagramas de Mermaid (visión general de la arquitectura, mapa de dependencias, capacidades/hoja de ruta)
• Tablas para cada conclusión estructurada: este público lee tablas, no texto narrativo
• Lenguaje empresarial: traduce los conceptos técnicos en impacto (fiabilidad, velocidad, coste, riesgo)

Guía 4: Guía para gestores de producto

Archivo: onboarding/product-manager-guide.md Público: Gestores de producto y partes interesadas ajenas a la ingeniería. Deben comprender qué hace el sistema, qué es posible y cuáles son los límites —NO cómo está construido—. Extensión: 400-800 líneas. Centrada en el usuario, enfocada en las funcionalidades y consciente de las limitaciones.

Secciones obligatorias

1. Qué hace este sistema: presentación concisa de 2-3 frases en un lenguaje accesible para el usuario (sin jerga)
2. Mapa del recorrido del usuario: gráfico Mermaid LR o diagrama de recorrido que muestre los flujos principales de los usuarios a través del sistema
3. Mapa de capacidades de las funcionalidades: tabla con las siguientes columnas: funcionalidad, estado (activa/beta/planificada/imposible), comportamiento visible para el usuario y limitaciones. Mapa exhaustivo de lo que está implementado y lo que no.
4. Modelo de datos (vista del producto): diagrama erDiagram simplificado de Mermaid que muestre las entidades con las que interactúan los usuarios. Explícalo en términos empresariales (p. ej., «Un proyecto tiene muchos documentos», no «relación FK»).
5. Configuración y indicadores de funcionalidades — Tabla: indicador/configuración, qué controla, valor por defecto, quién puede modificarlo. Qué se puede activar o desactivar sin necesidad de trabajo de ingeniería.
6. Capacidades de la API — Qué integraciones son posibles. Tabla: Capacidad, Punto final/Método, Autenticación, Límites de tasa. Dirigido a socios de integración, no a desarrolladores.
7. Rendimiento y SLA — Tiempos de respuesta, límites de rendimiento, objetivos de disponibilidad. Tabla: Operación, Latencia esperada, Límite de rendimiento, SLA actual.
8. Limitaciones y restricciones conocidas — Lista sincera de lo que el sistema no puede hacer o hace mal. Tabla: Limitación, impacto en el usuario, solución alternativa, corrección prevista.
9. Datos y privacidad — Qué datos se recopilan, dónde se almacenan, políticas de retención, estado de cumplimiento normativo. Tabla: Tipo de datos, ubicación de almacenamiento, retención, cumplimiento normativo.
10. Glosario — Términos del ámbito explicados en un lenguaje sencillo (sin jerga técnica)
11. Preguntas frecuentes — Más de 10 preguntas habituales que se le harían a un gestor de proyectos, respondidas de forma concisa

Normas

• CERO jerga técnica: nada de «middleware», «inyección de dependencias» ni «ORM». Utiliza un lenguaje sencillo.
• Enfoque centrado en el usuario: describe todo en términos de lo que experimentan los usuarios, no de cómo funciona el código
• Mínimo de 3 diagramas Mermaid (recorrido del usuario, modelo de datos, mapa de funcionalidades/resumen de capacidades)
• Tablas para cada conclusión estructurada: los gestores de proyectos revisan las tablas, no los textos narrativos
• Si hay que mencionar un concepto técnico, explícalo en una sola frase (p. ej., «Indicadores de funcionalidad: controles que nos permiten activar o desactivar funcionalidades sin implementar código»)
• Cada afirmación debe estar respaldada por pruebas: cita secciones de la wiki o archivos fuente para su verificación

Normas para los diagramas Mermaid (TODAS las guías)

TODOS los diagramas deben utilizar colores de modo oscuro:

• Relleno de los nodos: #2d333b; bordes: #6d5dfc; texto: #e6edf3
• Fondos de los subgrafos: #161b22, bordes: #30363d
• Líneas: #8b949e
• Si utilizas directivas de estilo en línea, utiliza rellenos oscuros con `color:#e6edf3`
• NO utilices
en las etiquetas de Mermaid (utiliza
o saltos de línea)

Validación

Tras generar cada guía, comprueba lo siguiente:

• Que todas las rutas de archivo mencionadas existan realmente en el repositorio
• Que todos los nombres de clases y métodos sean correctos (que no sean inventados)
• Que los diagramas de Mermaid se visualicen correctamente (sin errores de sintaxis)
• No hay etiquetas sin formato similares al HTML (genéricas como List) fuera de los bloques de código; envuélvelas entre comillas invertidas
• Que cada guía sea adecuada para su público objetivo — no debe haber código en las guías para ejecutivos ni para gestores de proyectos