brmdias/mejores-prácticas

Habilidad de Documentación de Mejores Prácticas

Automatiza el flujo de trabajo completo para documentar mejores prácticas en la base de conocimiento de TAM, reduciendo de 2 a 4 horas de trabajo manual a 10-15 minutos.

Uso

/mejores-practicas <nombre-del-tema>
/mp <nombre-del-tema>

Ejemplos:

• /mp patrones-timeout-webhook
• /mejores-practicas gestion-disco-runner
• /mp patrones-integracion-ansible

Qué Hace Esta Habilidad

Ejecuta el flujo de trabajo completo de documentación de mejores prácticas:

1. Validar y verificar existentes - Asegurar que no haya duplicados, manejar actualizaciones
2. Investigar base de conocimiento - Encontrar investigaciones similares, mejores prácticas, ejemplos de clientes
3. Buscar documentación - Encontrar guías oficiales e información de versiones
4. Buscar código del producto - Verificar detalles técnicos y valores por defecto (cuando sea relevante)
5. Buscar en GitHub - Encontrar issues de la comunidad, errores y solicitudes de características
6. Buscar en Jira - Localizar tickets de desarrollo internos y versiones de corrección
7. Búsqueda comunitaria - Obtener fuentes externas si es necesario (opcional)
8. Sintetizar hallazgos - Presentar resumen de la investigación para confirmación del usuario
9. Generar documento - Crear la mejor práctica siguiendo la estructura de TEMPLATE.md
10. Actualizar INDEX.md - Añadir a categorías, tabla alfabética y referencia rápida
11. Reportar finalización - Resumen completo con próximos pasos

Instrucciones

Cuando se invoque esta habilidad, siga estos pasos:

Paso 1: Analizar Argumentos y Validar

Extraer el nombre del tema de los argumentos:

• Requerido: nombre del tema (ej., "patrones-timeout-webhook")
• Convertir a kebab-case si no lo está
• Si el tema tiene más de 80 caracteres, advertir: "¿El tema parece demasiado amplio? Considere dividirlo."

Si no se proporciona ningún tema:

• Error: "Uso: /mejores-practicas "
• Mostrar ejemplos

Paso 2: Verificar si Existe una Mejor Práctica

Buscar mejores prácticas existentes con nombres similares:

Glob pattern="*${keywords}*" path="mejores-practicas/"

Lógica de decisión:

• Coincidencia exacta: Preguntar al usuario: "La mejor práctica existe en <archivo>. (1) Actualizar existente, (2) Crear nueva con diferente enfoque, (3) ¿Cancelar?"
• Coincidencias parciales: Listarlas, preguntar: "Se encontraron similares: <archivos>. (1) Actualizar una, (2) Crear nueva, (3) ¿Cancelar?"
• Sin coincidencias: Proceder con la creación

Si el usuario elige actualizar, anotar el nombre del archivo para usar Editar en lugar de Escribir.

Paso 3: Buscar en la Base de Conocimiento

Extraer palabras clave de búsqueda del nombre del tema (eliminar guiones, dividir en términos).

Buscar mejores prácticas:

Grep pattern="<keywords>" path="mejores-practicas/" output_mode="content" -C 3 head_limit=50

Buscar investigaciones:

Grep pattern="<keywords>" path="investigaciones/" output_mode="content" -C 3 head_limit=50

Buscar perfiles de clientes (si es relevante):

Grep pattern="<keywords>" path="clientes/" output_mode="files_with_matches"

Si se encuentran perfiles de clientes, Leerlos para recopilar contexto.

Recopilar y anotar:

• Mejores prácticas relacionadas (para la sección "Mejores Prácticas Relacionadas")
• Ejemplos de investigaciones (para la sección "Ejemplos del Mundo Real")
• Etiquetas comunes de documentos similares (para metadatos)
• Contexto del cliente cuando corresponda

Paso 4: Buscar Documentación Oficial

Grep pattern="<keywords>" path="repositorios/docs/" output_mode="content" -C 2 head_limit=30

Recopilar y anotar:

• Guías y recomendaciones oficiales
• Información específica de versiones
• Referencias y opciones de configuración
• Limitaciones o advertencias conocidas

Paso 5: Buscar Código del Producto (Condicional)

Cuándo buscar:

• El tema involucra un comportamiento específico de una característica
• Se necesitan valores de configuración por defecto
• Para entender características de rendimiento
• Para verificar restricciones técnicas

Grep pattern="<componente|clase>" path="repositorios/rundeckpro/" output_mode="content" head_limit=30

Recopilar y anotar:

• Valores de configuración por defecto
• Detalles de implementación y comportamiento
• Restricciones o límites técnicos
• Lógica específica de versiones

Paso 6: Buscar Issues de GitHub (a través del conector Runlayer)

Consultar GitHub a través del conector Runlayer — la CLI gh no está disponible en este entorno. Llame a search_tools para localizar la herramienta de búsqueda de issues de GitHub, luego execute_tool para buscar en rundeck/rundeck y rundeckpro/rundeckpro por <keywords> entre issues abiertos y cerrados. No use la shell para ejecutar gh.

Recopilar y anotar:

• Issues o errores conocidos
• Solicitudes de características y comentarios de la comunidad
• Soluciones alternativas y soluciones de la comunidad
• Números de issue para citar

Si el conector de GitHub no está disponible, anótelo y continúe.

Paso 7: Buscar en el Proyecto RUN de Jira (a través del conector Runlayer)

Consultar Jira a través del conector Runlayer. Llame a search_tools para localizar la herramienta de búsqueda de issues de Jira, luego execute_tool con el tool_name y argumentos exactos devueltos. No llame a mcp__atlassian__* directamente. Use parámetros equivalentes a:

jql: "project=RUN AND (summary ~ \"<keywords>\" OR description ~ \"<keywords>\") ORDER BY updated DESC"
maxResults: 15

Recopilar y anotar:

• Tickets de desarrollo internos
• Versiones de corrección e información de lanzamiento
• Estado de desarrollo y contexto
• Claves de Jira para citar (RUN-XXXX)

Manejo de errores: Si el conector de Jira no está disponible, anote "Búsqueda en Jira no disponible" y continúe.

Paso 8: Búsqueda Comunitaria (Opcional/Según sea Necesario)

Activar cuando:

• Se encuentren menos de 3 fuentes relevantes en los Pasos 3-7
• Patrón novedoso o emergente no bien documentado
• El usuario indique que se necesita una investigación más amplia

WebFetch con parámetros:
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<keywords>"
  prompt: "Encuentra discusiones sobre <tema>. Extrae: problemas reportados, soluciones propuestas, patrones recomendados, problemas comunes"

Recopilar y anotar:

• Soluciones y patrones de la comunidad
• Errores y problemas comunes
• Variaciones de implementación
• Importante: Marcar afirmaciones no verificadas, verificar contra la documentación oficial

Paso 9: Sintetizar Hallazgos y Obtener Confirmación del Usuario

Analizar todos los hallazgos de la investigación:

1. Identificar patrones entre las fuentes
2. Determinar recomendación: Enfoque principal con justificación
3. Identificar alternativas: Otros enfoques y por qué se prefiere el principal
4. Extraer implementación: Paso a paso con ejemplos de código
5. Documentar beneficios y compensaciones
6. Seleccionar metadatos:
   • Área del Producto: Determinar de estas categorías:
     • Diseño y Orquestación de Trabajos
     • Gestión y Segmentación de Nodos
     • Seguridad y Control de Acceso
     • Rendimiento y Escalabilidad
     • Integraciones y Webhooks
     • Arquitectura y Despliegue
     • Documentación y Mantenimiento
   • Aplica a Versión: De Jira/docs (ser específico como "Rundeck 5.6.0+" o conservador "Todas las versiones")
   • Etiquetas: Usar taxonomía existente de BP similares (escaneadas en el Paso 3), máximo 3-8 etiquetas

Presentar resumen de la investigación al usuario:

# Resumen de Investigación: <nombre-del-tema>

## Fuentes Encontradas
- Base de Conocimiento: X investigaciones, Y mejores prácticas
- Documentación: N páginas
- GitHub: P issues
- Jira: Q tickets
- Comunidad: [si se buscó]

## Enfoque Recomendado
[Resumen de 1-2 párrafos de la recomendación principal basada en la investigación]

## Patrones Clave Identificados
- [Patrón 1 de la investigación]
- [Patrón 2 de la investigación]
- [Patrón 3 de la investigación]

## Metadatos Propuestos
- **Área del Producto:** [categoría determinada]
- **Aplica a Versión:** [versión de la investigación]
- **Etiquetas:** #etiqueta1 #etiqueta2 #etiqueta3 [de BP similares]

## Verificación de Calidad
- ✓ [X] fuentes encontradas (mínimo 4 recomendadas)
- ✓ [Y] ejemplos de código/configuración disponibles
- ✓ [Z] ejemplos del mundo real encontrados

¿Listo para generar el documento?

Esperar confirmación del usuario. El usuario puede:

• Confirmar y continuar
• Solicitar cambios en metadatos o enfoque
• Pedir investigación adicional
• Cancelar el flujo de trabajo

NO proceder a la generación sin confirmación del usuario.

Paso 10: Generar el Documento de Mejores Prácticas

Una vez que el usuario confirme, generar el documento:

1. Leer la plantilla como referencia:

Read file_path="mejores-practicas/TEMPLATE.md"

2. Poblar todas las secciones con el contenido investigado:

Encabezado (líneas 1-6):

# [Nombre del Tema en Título]

**Última Actualización:** 2026-04-20
**Área del Producto:** [del Paso 9]
**Aplica a Versión:** [del Paso 9]
**Etiquetas:** #etiqueta1 #etiqueta2 #etiqueta3 [del Paso 9]

---

Caso de Uso / Escenario:

• Describir cuándo alguien necesita esto (de investigaciones + documentación)
• ¿Qué problema resuelve?
• ¿Para qué escenarios es relevante?

Recomendación:

• Guía clara y procesable (el "qué hacer")
• Enfoque principal de la síntesis
• Puede incluir una tabla si hay múltiples opciones

Implementación:

• Instrucciones paso a paso
• Múltiples patrones si es aplicable (Patrón 1, Patrón 2, etc.)
• Ejemplos de código de la documentación y la investigación de código

# Incluir ejemplos reales de YAML/configuración
# Usar fragmentos de código encontrados en la investigación

Por Qué Funciona:

• Explicación técnica de la investigación de código + documentación
• Principios o mecanismos subyacentes
• Por qué este enfoque es efectivo

Beneficios:

• Lista numerada de los hallazgos de la investigación
• Ventajas concretas (rendimiento, seguridad, mantenibilidad, etc.)
• Cuantificar cuando sea posible

Compensaciones / Advertencias:

• Limitaciones identificadas en la investigación
• Consideraciones de rendimiento
• Situaciones donde esto podría no aplicar
• ⚠️ Marcar información conflictiva si se encuentra

Alternativas Consideradas:

• Otros enfoques encontrados en la investigación
• Por qué se prefiere el enfoque recomendado
• Cuándo las alternativas podrían ser mejores

Ejemplos del Mundo Real:

• Enlaces a investigaciones: [Cliente/Caso](../investigaciones/YYYY-MM-DD-descripcion.md)
• Si no hay: "No hay investigaciones documentadas aún. Esta mejor práctica se basa en [documentación oficial/análisis de código/patrones comunitarios]."

Mejores Prácticas Relacionadas:

• Enlaces a documentos relacionados de la búsqueda en KB
• Formato: [Título](./nombre-archivo.md) - Breve descripción

Documentación Oficial:

• Enlaces a archivos del repositorio de documentación
• Issues de GitHub por número
• Tickets de Jira por clave
• Enlaces oficiales del sitio web

3. Verificaciones de calidad antes de escribir:

• ✓ Los 4 campos de metadatos poblados
• ✓ 3-8 etiquetas de la taxonomía existente
• ✓ Todas las secciones de la plantilla presentes
• ✓ Al menos 1 ejemplo de código/configuración
• ✓ Al menos 2 fuentes citadas
• ✓ Formato markdown adecuado

4. Escribir el documento:

Si es nueva creación:

Write file_path="mejores-practicas/<nombre-en-kebab>.md" content="<contenido-generado>"

Si es actualización de existente (del Paso 2):

Edit file_path="mejores-practicas/<nombre-archivo-existente>.md"

Actualizar las secciones relevantes manteniendo la estructura.

Paso 11: Actualizar INDEX.md

1. Leer el ÍNDICE actual:

Read file_path="mejores-practicas/INDEX.md"

2. Determinar la categoría principal de estas opciones (usar el emoji exactamente como se muestra):

   • 🎯 Diseño y Orquestación de Trabajos
   • 🖥️ Gestión y Segmentación de Nodos
   • 🔐 Seguridad y Control de Acceso
   • 📊 Rendimiento y Escalabilidad
   • 🔗 Integraciones y Webhooks
   • 🏗️ Arquitectura y Despliegue
   • 📝 Documentación y Mantenimiento

3. Actualizar tres secciones usando la herramienta Editar:

a) Sección de Categorías: Encontrar la categoría adecuada (ej., "### 🎯 Diseño y Orquestación de Trabajos") y añadir la entrada:

- [Título](./nombre-archivo.md) - Descripción de una línea #etiqueta1 #etiqueta2 #etiqueta3

Insertar alfabéticamente dentro de la categoría.

b) Tabla de Todas las Mejores Prácticas (Alfabéticas): Encontrar la posición alfabética correcta e insertar:

| [Título](./nombre-archivo.md) | Categoría [y Categorías Secundarias si aplica] | 2026-04-20 | [Casos relacionados o "N/A"] |

c) Sección de Referencia Rápida por Caso de Uso: Añadir 2-4 entradas "Necesito..." que reflejen casos de uso comunes:

- **...problema/tarea específica** → [Título](./nombre-archivo.md)

Mantener orden alfabético.

4. Actualizar fecha de "Última Actualización": Cambiar la fecha en la parte superior:

**Última Actualización:** 2026-04-20

5. Ejecutar actualizaciones con la herramienta Editar: Usar Editar para hacer cada cambio (o combinarlos si están cerca):

Edit file_path="mejores-practicas/INDEX.md" old_string="<texto-existente>" new_string="<texto-actualizado>"

Paso 12: Reportar Finalización

Proporcionar un resumen completo de finalización:

✅ ¡Mejor Práctica Creada Exitosamente!

## Detalles del Documento
**Título:** [Título Completo]
**Archivo:** mejores-practicas/<nombre-archivo>.md
**Categoría:** [Categoría Principal]
**Etiquetas:** #etiqueta1 #etiqueta2 #etiqueta3

## Resumen de la Investigación
- Base de Conocimiento: X investigaciones, Y mejores prácticas
- Documentación: N páginas
- GitHub: P issues
- Jira: Q tickets
- Comunidad: [si se buscó]
- **Total de fuentes:** [recuento]

## Secciones del Documento Completadas
✓ Caso de Uso / Escenario
✓ Recomendación con [recuento] patrones
✓ Implementación con [recuento] ejemplos de código
✓ Por Qué Funciona
✓ [recuento] Beneficios listados
✓ [recuento] Compensaciones documentadas
✓ [recuento] Alternativas consideradas
✓ Ejemplos del mundo real: [enlaces o "documentación pendiente"]
✓ [recuento] Mejores prácticas relacionadas enlazadas
✓ [recuento] Referencias de documentación oficial

## INDEX.md Actualizado
✓ Añadido a [Nombre de Categoría]
✓ Añadido a la tabla alfabética (fila [N])
✓ Añadidas [recuento] entradas de referencia rápida
✓ Actualizada fecha de "Última Actualización"

## Próximos Pasos
1. Revisar el documento en: mejores-practicas/<nombre-archivo>.md
2. Probar la implementación en el sandbox si aplica
3. Compartir con el equipo: `/compartir-kb "<título>" mejores-practicas/<nombre-archivo>.md`
4. Enlazar desde perfiles de clientes relevantes si aplica

Si fue una actualización en lugar de creación:

✅ ¡Mejor Práctica Actualizada Exitosamente!

## Documento Actualizado
**Título:** [Título Completo]
**Archivo:** mejores-practicas/<nombre-archivo>.md
[resto del resumen adaptado para escenario de actualización]

Directrices de Calidad

Calidad de la Investigación

• Buscar al menos 4 categorías de fuentes (KB, documentación, código, rastreadores externos)
• Citar rutas de archivo específicas para referencias de código/documentación
• Enlazar issues de GitHub por número (#1234)
• Enlazar tickets de Jira por clave (RUN-1234)
• Verificar afirmaciones de la comunidad contra fuentes oficiales
• Marcar información no verificada o conflictiva

Calidad del Documento

• Claridad: Cada sección debe ser inmediatamente procesable o informativa
• Completitud: Todas las secciones de la plantilla completadas (sin TODOs)
• Basado en evidencia: Todas las recomendaciones respaldadas por fuentes
• Práctico: Incluir ejemplos reales de código/configuración, no solo prosa
• Honesto: Documentar compensaciones y advertencias