brmdias/investigación

Habilidad de Flujo de Investigación

Automatiza el proceso completo de investigación del TAM para incidencias de clientes.

Uso

/investigar <nombre-cliente> <descripción-incidencia>

Ejemplos:

• /investigar LSEG "error de timeout en webhook"
• /investigar "Network International" "autenticación de plugin BeyondTrust"
• /investigar Roche "el scheduler no dispara trabajos"

Qué hace esta habilidad

Ejecuta el flujo de trabajo completo de investigación desde CLAUDE.md:

1. Encontrar perfil del cliente - Localizar y leer los detalles del entorno del cliente
2. Buscar en base de conocimiento - Encontrar investigaciones similares y mejores prácticas
3. Revisar documentación - Verificar si el comportamiento está documentado
4. Verificar en código - Buscar en el código fuente del producto el comportamiento real
5. Revisar rastreadores externos - Buscar en GitHub Issues y Jira bugs/conocimiento conocido
6. Recomendar entorno de prueba - Sugerir el sandbox adecuado según el tipo de incidencia
7. Resumir hallazgos - Proporcionar un resumen estructurado con referencias
8. Documentar investigación - Crear un nuevo archivo de investigación en investigations/ usando la plantilla

Instrucciones

Cuando se invoque esta habilidad, sigue estos pasos:

Paso 1: Extraer parámetros

A partir de los argumentos, identifica:

• customer_name: El nombre del cliente/empresa
• issue_keywords: Términos clave que describen la incidencia (mensajes de error, características, componentes)

Paso 2: Encontrar perfil del cliente

Grep pattern="<customer_name>" path="customers/" output_mode="files_with_matches"

Si se encuentra:

• Read el archivo de perfil del cliente
• Anota: entorno (cloud/on-prem), versión de Rundeck, escala, problemas pasados
• Almacena el contexto del cliente para después

Si no se encuentra:

• Anota: "Perfil de cliente no encontrado - puede ser prospecto o primer contacto"
• Continúa la investigación

Paso 3: Buscar en base de conocimiento

Investigaciones similares:

Grep pattern="<issue_keywords>" glob="investigations/**/*.md" output_mode="content" -C 3

Mejores prácticas relacionadas:

Grep pattern="<issue_keywords>" glob="best-practices/**/*.md" output_mode="content" -C 2

Para cada resultado:

• Anota la ruta del archivo, la fecha (del nombre del archivo si es investigación) y los hallazgos clave
• Identifica si es coincidencia exacta o patrón similar
• Extrae soluciones o workarounds

Paso 4: Revisar documentación

Grep pattern="<issue_keywords>" path="repositories/docs/" output_mode="content" -C 2

Determina:

• ¿Es este comportamiento documentado?
• ¿Hay opciones de configuración o limitaciones conocidas?
• ¿La documentación coincide con la expectativa del cliente?

Paso 5: Verificar en código del producto

Grep pattern="<relevant_class_or_method>" path="repositories/rundeckpro/" output_mode="content" head_limit=50

Busca:

• Comportamiento de implementación real
• Valores predeterminados o constantes
• Fuentes de mensajes de error
• Lógica específica de versión

Paso 6: Revisar rastreadores externos

Incidencias de la comunidad de GitHub (a través del conector Runlayer):

Consulta GitHub a través del conector Runlayer. Llama a search_tools para localizar la herramienta de búsqueda de incidencias de GitHub, luego execute_tool para buscar en rundeck/rundeck y rundeckpro/rundeckpro para <issue_keywords> en incidencias abiertas y cerradas (límite ~10 cada una). No uses gh en shell.

Seguimiento de desarrollo en Jira (a través del conector Runlayer):

Consulta Jira a través del conector Runlayer. Llama a search_tools para localizar la herramienta de búsqueda de incidencias de Jira, luego execute_tool con el tool_name y argumentos exactos devueltos para buscar el proyecto RUN para <issue_keywords> ordenado por fecha de actualización (JQL equivalente: project=RUN AND text~"<issue_keywords>" ORDER BY updated DESC). No llames directamente a herramientas mcp__atlassian__*.

Para cada resultado relevante:

• Anota el número de incidencia, estado y resumen
• Verifica si está corregido en una versión específica
• Anota cualquier workaround mencionado

Paso 7: Recomendar entorno de prueba

Haz esto solo si hay entornos sandbox disponibles. Si no, anota: "No hay entornos sandbox disponibles - recomienda WAR local para reproducción rápida". Basado en las características de la incidencia, recomienda el sandbox:

Lógica de decisión: Analiza los entornos sandbox disponibles y sugiere el más adecuado. Referencia: Read .claude/memory/sandbox-environments.md para detalles de conexión si es necesario No te conectes al sandbox dentro de esta habilidad, solo proporciona la recomendación.

Paso 8: Generar resumen estructurado

Proporciona los hallazgos en este formato:

# Resumen de Investigación: <customer_name> - <issue_description>

## Contexto del Cliente
- **Perfil:** [encontrado/no encontrado]
- **Entorno:** [cloud/on-prem, versión, escala]
- **Problemas Pasados:** [historial relevante si existe]

## Hallazgos en Base de Conocimiento

### Investigaciones Similares
- [investigation-file.md](path) - <resumen breve>
- [Estado: resuelto/workaround/abierto]

### Mejores Prácticas Relevantes
- [best-practice-file.md](path) - <resumen breve>

## Estado de la Documentación
- **Documentado:** [Sí/No/Parcial]
- **Referencias:** [rutas de archivo con números de línea]
- **Detalles Clave:** [configuración relevante, limitaciones o guía]

## Análisis de Código
- **Componente:** [nombres de clase/método]
- **Comportamiento:** [comportamiento de implementación real]
- **Fuente:** [file_path:line_number]

## Estado de Rastreadores Externos

### Incidencias de GitHub
- rundeck/rundeck#<número> - <resumen> [estado]
- rundeckpro/rundeckpro#<número> - <resumen> [estado]

### Incidencias de Jira
- RUN-<número> - <resumen> [estado, versión de corrección si aplica]

## Entorno de Prueba Recomendado
**Entorno:** [AWS EKS / AWS EC2 / WAR Local / PDT-RDTAM]
**Motivo:** [tipo de base de datos / detalles de la incidencia / necesidades de prueba]
**Conexión:** Ver .claude/memory/sandbox-environments.md

## Próximos Pasos
1. [Acción inmediata]
2. [Recomendación de prueba]
3. [Guía de comunicación con el cliente]

## Recursos Relacionados
- Perfil del cliente: [ruta si existe]
- Investigaciones: [lista de archivos relacionados]
- Mejores prácticas: [lista de guías aplicables]
- Documentación: [páginas de documentación clave]

Directrices de Calidad

Sé exhaustivo pero conciso:

• No incluyas todos los resultados de búsqueda - prioriza los hallazgos relevantes
• Cita rutas de archivo para todas las referencias (ej., investigations/2026-03-15-issue.md:45)
• Marca claramente lo desconocido ("No se encontraron casos similares" vs afirmaciones vagas)

Proporciona información procesable:

• No solo enumeres hallazgos - sintetiza patrones
• Si múltiples investigaciones muestran la misma solución, resáltala
• Si la documentación entra en conflicto con el código, señálalo explícitamente

Considera el contexto del cliente:

• Adapta las recomendaciones al entorno del cliente (cloud vs on-prem, versión)
• Referencia sus problemas pasados si existen patrones relevantes
• Ajusta la recomendación del entorno de prueba para que coincida con su configuración

Manejo de Errores

Si el cliente no se encuentra:

• Continúa la investigación sin contexto del cliente
• Anota: "Recomendar crear perfil de cliente si es un compromiso recurrente"

Si no hay resultados en la base de conocimiento:

• Prueba términos de búsqueda más amplios
• Anota: "Incidencia nueva - considera documentar como investigación después de la resolución"

Si los rastreadores externos no están disponibles:

• Anota la falla de la herramienta
• Continúa con la información disponible
• Sugiere verificación manual: "La búsqueda en GitHub falló - verifica manualmente las incidencias de rundeck/rundeck"

Si la descripción de la incidencia es ambigua:

• Haz el mejor esfuerzo con las palabras clave disponibles
• Anota: "Descripción de incidencia ambigua - la búsqueda cubrió: [lista de términos usados]"
• Sugiere: "Refina la búsqueda con mensajes de error específicos o nombres de componentes"

Paso 9: Documentar la Investigación

Después de completar la investigación y presentar el resumen, crea un nuevo archivo de investigación para documentar los hallazgos:

Creación del archivo:

investigations/YYYY-MM-DD-breve-descripcion-en-kebab-case.md

Usa la plantilla: Read investigations/TEMPLATE.md para la estructura

Completa con:

• Título: Breve descripción de la incidencia
• Fecha: Fecha de hoy (formato YYYY-MM-DD)
• Cliente: Nombre del cliente de la investigación
• Área del Producto: Componente relevante (webhooks, trabajos, nodos, etc.)
• Etiquetas: Descubiertas de investigaciones similares, más etiquetas específicas de la incidencia
• Declaración del Problema: Descripción de la incidencia proporcionada por el usuario
• Detalles del Entorno: Del perfil del cliente (si se encontró)
• Pasos de Investigación: Resumen de los pasos de búsqueda realizados
• Causa Raíz: Si se identificó durante la investigación
• Solución/Resolución: Si se encontró en la base de conocimiento o documentación
• Documentación Relacionada: Referencias descubiertas durante la búsqueda
• Referencias de Código/Documentación: Rutas de archivo con números de línea de los resultados de búsqueda
• Notas/Aprendizajes: Cualquier patrón o insight de la investigación

Después de crear el archivo:

1. Actualiza investigations/INDEX.md con la nueva entrada:
   • Añadir a la sección de categoría apropiada
   • Añadir a la tabla cronológica
   • Añadir etiquetas a la sección "Búsqueda Rápida por Etiqueta"
   • Actualizar la fecha de "Última Actualización"

Notas

• La investigación crea un registro permanente en la base de conocimiento
• Tiempo de ejecución promedio: 30-60 segundos para búsqueda + 2-3 minutos para documentación
• Todos los hallazgos son investigación - las pruebas reales aún se requieren en el entorno recomendado
• Para consejos de posicionamiento estratégico, invoca por separado Read .claude/memory/tam-advisory-philosophy.md
• La documentación asegura que el conocimiento sea capturado y buscable para futuras investigaciones