By name: quinotospec-onboard-support description: Especificaciones para generar el documento de onboarding orientado a equipos de soporte técnico, help desk o atención al cliente técnica. Foco en comportamiento observable del sistema, endpoints relevantes, servicios externos e identificación de puntos de falla comunes.
Skill: Onboard Soporte
Aplica estas especificaciones al generar el documento de onboarding cuando el ROL seleccionado es Soporte.
Audiencia
Personas de soporte técnico, help desk nivel 1/2, o atención al cliente técnica. Deben entender qué hace el sistema desde la perspectiva del usuario final, saber identificar dónde puede fallar, y conocer qué información recopilar ante un incidente. No necesariamente escriben código, pero pueden leer logs y manejar herramientas técnicas básicas.
Tono y Estilo
- Claro y operacional. Orientado a "qué hacer cuando pasa X".
- Usar listas de verificación y tablas de decisión.
- Incluir ejemplos de mensajes de error comunes cuando se pueda inferir del codebase o discovery.
- Destacar con ⚠️ los puntos de falla más frecuentes o críticos.
Secciones a Incluir y Nivel de Detalle
| Sección | Nivel | Instrucción |
|---|---|---|
| ¿Qué es este proyecto? | Alto | 4-5 oraciones. Describir desde la perspectiva del usuario final: qué puede hacer, qué espera recibir, qué no contempla el sistema. |
| Cómo levantar el proyecto | Omitir | No incluir. Reemplazar por nota: "El deployment lo gestiona el equipo de desarrollo/DevOps. Para consultas de entorno, escalar al equipo técnico." |
| Arquitectura del Sistema | Medio | Descripción funcional de los componentes como "cajas negras": qué reciben como entrada y qué producen como salida. Sin código. Incluir diagrama Mermaid si existe, con anotaciones en lenguaje operacional. |
| Endpoints Principales | Máximo | Tabla completa con método, ruta, descripción funcional, qué significa cada código de respuesta (200, 400, 401, 404, 500) para el usuario. |
| Modelos de Datos Clave | Medio | Solo los modelos que el equipo de soporte necesita para identificar registros del usuario (ej. User, Order, Session). Incluir los campos identificadores clave (ID, email, estado). |
| Estado Actual del Proyecto | Bajo | Solo mencionar si hay propuestas activas que puedan afectar comportamiento del sistema próximamente. |
| Acuerdos del Equipo (DoR/DoD) | Omitir | No relevante para soporte. |
| Actividad Reciente | Alto | Últimos 10 cambios del changelog — importante para correlacionar incidentes con deploys recientes. |
| Primeros Pasos Sugeridos | Alto | 6 pasos orientados a entender el sistema desde el lado del usuario y prepararse para atender tickets. |
| Recursos y Documentación | Medio | Solo los recursos útiles para soporte. |
Sección Extra: Guía de Incidentes Comunes
Incluir siempre esta sección para soporte, generándola a partir de lo que se pueda inferir del codebase, endpoints y servicios externos detectados:
## 🚨 Guía de Incidentes Comunes
### Cómo escalar un incidente
1. Recopilar: ID de usuario afectado, timestamp del error, mensaje de error exacto, endpoint o acción que ejecutaba.
2. Verificar el changelog reciente — ¿hubo un deploy en las últimas horas?
3. Si el error es 5xx → escalar a desarrollo inmediatamente con los datos recopilados.
4. Si el error es 4xx → verificar que el usuario tenga los permisos correctos / datos válidos.
### Servicios externos que pueden fallar
| Servicio | Propósito | Síntoma de falla | Acción |
|---|---|---|---|
| [servicio detectado en 05-data-and-services.md] | [qué hace] | [cómo se manifiesta] | [escalar a / verificar] |
### Variables de entorno críticas para producción
[Listar de 06-devops-ci-security.md las variables más críticas cuya ausencia causa fallas catastróficas. No incluir valores, solo nombres y consecuencia de su ausencia.]
Primeros Pasos — Plantilla para Soporte
- Leer la sección "¿Qué es este proyecto?" para entender qué puede y no puede hacer el sistema.
- Familiarizarse con los endpoints principales y sus códigos de respuesta.
- Identificar los servicios externos integrados (ver tabla en "Guía de Incidentes Comunes").
- Revisar el changelog reciente para saber qué cambió recientemente en el sistema.
- Solicitar acceso de solo lectura a los logs de producción al equipo de DevOps.
- Generar un ticket de prueba y verificar que el flujo completo funcione correctamente.
Lo que NO incluir
- Comandos de desarrollo o configuración local.
- Arquitectura interna detallada o patrones de diseño.
- Acuerdos del equipo de desarrollo (DoR/DoD).
- Detalles de implementación de modelos de datos más allá de los campos identificadores.