brmdias/best-practice

Skill de Documentação de Melhores Práticas

Automatiza o fluxo de trabalho completo para documentar melhores práticas na base de conhecimento TAM, reduzindo de 2 a 4 horas de trabalho manual para 10 a 15 minutos.

Uso

/best-practice <nome-do-tópico>
/bp <nome-do-tópico>

Exemplos:

• /bp webhook-timeout-patterns
• /best-practice runner-disk-management
• /bp ansible-integration-patterns

O Que Esta Skill Faz

Executa o fluxo de trabalho completo de documentação de melhores práticas:

1. Validar e verificar existente - Garantir que não há duplicatas, gerenciar atualizações
2. Pesquisar base de conhecimento - Encontrar investigações similares, melhores práticas, exemplos de clientes
3. Pesquisar documentação - Encontrar orientações oficiais e informações de versão
4. Pesquisar código do produto - Verificar detalhes técnicos e padrões (quando relevante)
5. Pesquisar GitHub - Encontrar issues da comunidade, bugs e solicitações de funcionalidades
6. Pesquisar Jira - Localizar tickets de desenvolvimento internos e versões de correção
7. Pesquisa na comunidade - WebFetch em fontes externas se necessário (opcional)
8. Sintetizar descobertas - Apresentar resumo da pesquisa para confirmação do usuário
9. Gerar documento - Criar melhor prática seguindo a estrutura do TEMPLATE.md
10. Atualizar INDEX.md - Adicionar às categorias, tabela alfabética e referência rápida
11. Relatar conclusão - Resumo abrangente com próximos passos

Instruções

Quando esta skill for invocada, siga estas etapas:

Etapa 1: Analisar Argumentos e Validar

Extraia o nome do tópico dos argumentos:

• Obrigatório: nome do tópico (ex.: "webhook-timeout-patterns")
• Converter para kebab-case se ainda não estiver
• Se o tópico tiver mais de 80 caracteres, avisar: "Tópico parece amplo. Considere dividir?"

Se nenhum tópico for fornecido:

• Erro: "Uso: /best-practice <nome-do-tópico>"
• Mostrar exemplos

Etapa 2: Verificar se já Existe Melhor Prática

Pesquisar por melhores práticas existentes com nomes semelhantes:

Glob pattern="*${palavras-chave}*" path="best-practices/"

Lógica de decisão:

• Correspondência exata: Perguntar ao usuário: "Melhor prática existente em <arquivo>. (1) Atualizar existente, (2) Criar nova com foco diferente, (3) Cancelar?"
• Correspondências parciais: Listá-las, perguntar: "Encontradas semelhantes: <arquivos>. (1) Atualizar uma, (2) Criar nova, (3) Cancelar?"
• Nenhuma correspondência: Prosseguir com a criação

Se o usuário escolher atualizar, anotar o nome do arquivo para Editar posteriormente, em vez de Escrever.

Etapa 3: Pesquisar Base de Conhecimento

Extrair palavras-chave de pesquisa do nome do tópico (remover hífens, dividir em termos).

Pesquisar melhores práticas:

Grep pattern="<palavras-chave>" path="best-practices/" output_mode="content" -C 3 head_limit=50

Pesquisar investigações:

Grep pattern="<palavras-chave>" path="investigations/" output_mode="content" -C 3 head_limit=50

Pesquisar perfis de clientes (se relevante):

Grep pattern="<palavras-chave>" path="customers/" output_mode="files_with_matches"

Se perfis de clientes forem encontrados, lê-los para obter contexto.

Coletar e anotar:

• Melhores práticas relacionadas (para a seção "Melhores Práticas Relacionadas")
• Exemplos de investigação (para a seção "Exemplos do Mundo Real")
• Tags comuns de documentos semelhantes (para metadados)
• Contexto do cliente quando aplicável

Etapa 4: Pesquisar Documentação Oficial

Grep pattern="<palavras-chave>" path="repositories/docs/" output_mode="content" -C 2 head_limit=30

Coletar e anotar:

• Orientações e recomendações oficiais
• Informações específicas de versão
• Referências e opções de configuração
• Limitações ou ressalvas conhecidas

Etapa 5: Pesquisar Código do Produto (Condicional)

Quando pesquisar:

• O tópico envolve comportamento específico de funcionalidade
• Necessário valores de configuração padrão
• Compreender características de desempenho
• Verificar restrições técnicas

Grep pattern="<componente|classe>" path="repositories/rundeckpro/" output_mode="content" head_limit=30

Coletar e anotar:

• Valores de configuração padrão
• Detalhes de implementação e comportamento
• Restrições ou limites técnicos
• Lógica específica de versão

Etapa 6: Pesquisar Issues do GitHub (via conector Runlayer)

Consultar o GitHub através do conector Runlayer — a CLI gh não está disponível neste ambiente. Chame search_tools para localizar a ferramenta de pesquisa de issues do GitHub, depois execute_tool para pesquisar rundeck/rundeck e rundeckpro/rundeckpro por <palavras-chave> em issues abertas e fechadas. Não use shell para o gh.

Coletar e anotar:

• Issues ou bugs conhecidos
• Solicitações de funcionalidades e feedback da comunidade
• Soluções alternativas e soluções da comunidade
• Números de issues para citação

Se o conector do GitHub não estiver disponível, anote e continue.

Etapa 7: Pesquisar Projeto Jira RUN (via conector Runlayer)

Consultar o Jira através do conector Runlayer. Chame search_tools para localizar a ferramenta de pesquisa de issues do Jira, depois execute_tool com o tool_name e argumentos exatos retornados. Não chame ferramentas mcp__atlassian__* diretamente. Use parâmetros equivalentes a:

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

Coletar e anotar:

• Tickets de desenvolvimento internos
• Versões de correção e informações de lançamento
• Status de desenvolvimento e contexto
• Chaves Jira para citação (RUN-XXXX)

Tratamento de erros: Se o conector do Jira não estiver disponível, anote "Pesquisa Jira indisponível" e continue.

Etapa 8: Pesquisa na Comunidade (Opcional/Conforme Necessário)

Acionar quando:

• Menos de 3 fontes relevantes encontradas nas Etapas 3-7
• Padrão novo ou emergente não bem documentado
• Usuário indica que pesquisa mais ampla é necessária

WebFetch com parâmetros:
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<palavras-chave>"
  prompt: "Encontre discussões sobre <tópico>. Extraia: problemas relatados, soluções propostas, padrões recomendados, problemas comuns"

Coletar e anotar:

• Soluções e padrões da comunidade
• Armadilhas e problemas comuns
• Variações de implementação
• Importante: Sinalizar alegações não verificadas, verificar com documentação oficial

Etapa 9: Sintetizar Descobertas e Obter Confirmação do Usuário

Analisar todos os resultados da pesquisa:

1. Identificar padrões entre fontes
2. Determinar recomendação: Abordagem principal com justificativa
3. Identificar alternativas: Outras abordagens e por que a principal é preferida
4. Extrair implementação: Passo a passo com exemplos de código
5. Documentar benefícios e trade-offs
6. Selecionar metadados:
   • Área do Produto: Determinar entre estas categorias:
     • Design e Orquestração de Jobs
     • Gerenciamento e Segmentação de Nós
     • Segurança e Controle de Acesso
     • Desempenho e Escalabilidade
     • Integrações e Webhooks
     • Arquitetura e Implantação
     • Documentação e Manutenção
   • Aplica-se à Versão: Do Jira/docs (seja específico como "Rundeck 5.6.0+" ou conservador "Todas as versões")
   • Tags: Usar taxonomia existente de BPs semelhantes (escaneie tags encontradas na Etapa 3), máximo de 3-8 tags

Apresentar resumo da pesquisa ao usuário:

# Resumo da Pesquisa: <nome-do-tópico>

## Fontes Encontradas
- Base de Conhecimento: X investigações, Y melhores práticas
- Documentação: N páginas
- GitHub: P issues
- Jira: Q tickets
- Comunidade: [se pesquisado]

## Abordagem Recomendada
[Resumo de 1-2 parágrafos da recomendação principal com base na pesquisa]

## Principais Padrões Identificados
- [Padrão 1 da pesquisa]
- [Padrão 2 da pesquisa]
- [Padrão 3 da pesquisa]

## Metadados Propostos
- **Área do Produto:** [categoria determinada]
- **Aplica-se à Versão:** [versão da pesquisa]
- **Tags:** #tag1 #tag2 #tag3 [de BPs semelhantes]

## Verificação de Qualidade
- ✓ [X] fontes encontradas (mínimo de 4 recomendado)
- ✓ [Y] exemplos de código/config disponíveis
- ✓ [Z] exemplos do mundo real encontrados

Pronto para gerar o documento?

Aguardar confirmação do usuário. O usuário pode:

• Confirmar e prosseguir
• Solicitar alterações nos metadados ou abordagem
• Pedir pesquisa adicional
• Cancelar o fluxo de trabalho

Não prossiga para a geração sem confirmação do usuário.

Etapa 10: Gerar Documento de Melhor Prática

Após o usuário confirmar, gerar o documento:

1. Ler template para referência:

Read file_path="best-practices/TEMPLATE.md"

2. Preencher todas as seções com conteúdo pesquisado:

Cabeçalho (linhas 1-6):

# [Nome do Tópico em Title Case]

**Última Atualização:** 2026-04-20
**Área do Produto:** [da Etapa 9]
**Aplica-se à Versão:** [da Etapa 9]
**Tags:** #tag1 #tag2 #tag3 [da Etapa 9]

---

Caso de Uso / Cenário:

• Descrever quando alguém precisa disso (de investigações + documentação)
• Que problema resolve?
• Para quais cenários é relevante?

Recomendação:

• Orientação clara e acionável (o "o que fazer")
• Abordagem principal da síntese
• Pode incluir uma tabela se houver múltiplas opções

Implementação:

• Passo a passo de como fazer
• Múltiplos padrões se aplicáveis (Padrão 1, Padrão 2, etc.)
• Exemplos de código da documentação e pesquisa de código

# Incluir exemplos reais de YAML/config
# Usar trechos de código encontrados na pesquisa

Por Que Isso Funciona:

• Explicação técnica da pesquisa de código + documentação
• Princípios ou mecanismos subjacentes
• Por que esta abordagem é eficaz

Benefícios:

• Lista numerada das descobertas da pesquisa
• Vantagens concretas (desempenho, segurança, capacidade de manutenção, etc.)
• Quantificar quando possível

Trade-offs / Ressalvas:

• Limitações identificadas na pesquisa
• Considerações de desempenho
• Situações em que isso pode não se aplicar
• ⚠️ Sinalizar informações conflitantes se encontradas

Alternativas Consideradas:

• Outras abordagens encontradas na pesquisa
• Por que a abordagem recomendada é preferida
• Quando as alternativas podem ser melhores

Exemplos do Mundo Real:

• Links para investigações: [Cliente/Caso](../investigations/YYYY-MM-DD-descrição.md)
• Se nenhum: "Nenhuma investigação documentada ainda. Esta melhor prática é baseada em [documentação oficial/análise de código/padrões da comunidade]."

Melhores Práticas Relacionadas:

• Links para documentos relacionados da pesquisa na KB
• Formato: [Título](./nome-do-arquivo.md) - Breve descrição

Documentação Oficial:

• Links para arquivos do repositório de documentação
• Issues do GitHub por número
• Tickets Jira por chave
• Links do site oficial

3. Verificações de qualidade antes de escrever:

• ✓ Todos os 4 campos de metadados preenchidos
• ✓ 3-8 tags da taxonomia existente
• ✓ Todas as seções do template presentes
• ✓ Pelo menos 1 exemplo de código/config
• ✓ Pelo menos 2 fontes citadas
• ✓ Formatação markdown adequada

4. Escrever o documento:

Se criando novo:

Write file_path="best-practices/<nome-do-tópico-em-kebab-case>.md" content="<conteúdo-gerado>"

Se atualizando existente (da Etapa 2):

Edit file_path="best-practices/<nome-do-arquivo-existente>.md"

Atualizar seções relevantes preservando a estrutura.

Etapa 11: Atualizar INDEX.md

1. Ler INDEX atual:

Read file_path="best-practices/INDEX.md"

2. Determinar categoria principal entre estas opções (usar emoji exatamente como mostrado):

   • 🎯 Design e Orquestração de Jobs
   • 🖥️ Gerenciamento e Segmentação de Nós
   • 🔐 Segurança e Controle de Acesso
   • 📊 Desempenho e Escalabilidade
   • 🔗 Integrações e Webhooks
   • 🏗️ Arquitetura e Implantação
   • 📝 Documentação e Manutenção

3. Atualizar três seções usando a ferramenta Editar:

a) Seção de Categorias: Encontrar a categoria apropriada (ex.: "### 🎯 Design e Orquestração de Jobs") e adicionar entrada:

- [Título](./nome-do-arquivo.md) - Descrição de uma linha #tag1 #tag2 #tag3

Inserir em ordem alfabética dentro da categoria.

b) Tabela de Todas as Melhores Práticas (Alfabética): Encontrar a posição alfabética correta e inserir:

| [Título](./nome-do-arquivo.md) | Categoria [& Categorias Secundárias se aplicável] | 2026-04-20 | [Casos relacionados ou "N/A"] |

c) Seção de Referência Rápida por Caso de Uso: Adicionar 2-4 entradas "Preciso de..." que reflitam casos de uso comuns:

- **...problema/tarefa específico** → [Título](./nome-do-arquivo.md)

Manter em ordem alfabética.

4. Atualizar data de "Última Atualização": Alterar a data no topo:

**Última Atualização:** 2026-04-20

5. Executar atualizações com a ferramenta Editar: Usar Editar para fazer cada alteração (ou combinar se estiverem próximas):

Edit file_path="best-practices/INDEX.md" old_string="<texto-existente>" new_string="<texto-atualizado>"

Etapa 12: Relatar Conclusão

Fornecer resumo abrangente da conclusão:

✅ Melhor Prática Criada com Sucesso!

## Detalhes do Documento
**Título:** [Título Completo]
**Arquivo:** best-practices/<nome-do-arquivo>.md
**Categoria:** [Categoria Principal]
**Tags:** #tag1 #tag2 #tag3

## Resumo da Pesquisa
- Base de Conhecimento: X investigações, Y melhores práticas
- Documentação: N páginas
- GitHub: P issues
- Jira: Q tickets
- Comunidade: [se pesquisado]
- **Total de fontes:** [contagem]

## Seções do Documento Concluídas
✓ Caso de Uso / Cenário
✓ Recomendação com [contagem] padrões
✓ Implementação com [contagem] exemplos de código
✓ Por Que Isso Funciona
✓ [contagem] Benefícios listados
✓ [contagem] Trade-offs documentados
✓ [contagem] Alternativas consideradas
✓ Exemplos do mundo real: [links ou "documentação pendente"]
✓ [contagem] Melhores práticas relacionadas vinculadas
✓ [contagem] Referências de documentação oficial

## INDEX.md Atualizado
✓ Adicionado a [Nome da Categoria]
✓ Adicionado à tabela alfabética (linha [N])
✓ Adicionado [contagem] entradas de referência rápida
✓ Data de "Última Atualização" atualizada

## Próximos Passos
1. Revisar o documento em: best-practices/<nome-do-arquivo>.md
2. Testar a implementação em sandbox se aplicável
3. Compartilhar com a equipe: `/share-kb "<título>" best-practices/<nome-do-arquivo>.md`
4. Vincular de perfis de clientes relevantes se aplicável

Se foi uma atualização em vez de criação:

✅ Melhor Prática Atualizada com Sucesso!

## Documento Atualizado
**Título:** [Título Completo]
**Arquivo:** best-practices/<nome-do-arquivo>.md
[restante do resumo adaptado para cenário de atualização]

Diretrizes de Qualidade

Qualidade da Pesquisa

• Pesquisar mínimo de 4 categorias de fontes (KB, documentação, código, rastreadores externos)
• Citar caminhos de arquivo específicos para referências de código/documentação
• Vincular issues do GitHub por número (#1234)
• Vincular tickets Jira por chave (RUN-1234)
• Verificar alegações da comunidade com fontes oficiais
• Sinalizar informações não verificadas ou conflitantes

Qualidade do Documento

• Clareza: Cada seção imediatamente acionável ou informativa
• Completude: Todas as seções do template preenchidas (sem TODOs)
• Baseado em evidências: Todas as recomendações apoiadas por fontes
• Prático: Incluir exemplos reais de código/config, não apenas prosa
• Honesto: Trade-offs e ressalvas documentados

Fluxo de Trabalho Resumido

flowchart TD
    A[Invocação] --> B[Validar & Verificar Existente]
    B --> C{Pesquisar KB}
    C --> D{Pesquisar Documentação}
    D --> E{Pesquisar Código?}
    E -->|Sim| F[Pesquisar Código]
    E -->|Não| G{Pesquisar GitHub}
    F --> G
    G --> H{Pesquisar Jira}
    H --> I{Pesquisar Comunidade?}
    I -->|Sim| J[WebFetch]
    I -->|Não| K[Sintetizar]
    J --> K
    K --> L[Confirmação do Usuário]
    L -->|Confirmado| M[Gerar Documento]
    L -->|Alterar| K
    M --> N[Atualizar INDEX.md]
    N --> O[Relatar Conclusão]

Notas Finais

• Esta skill depende de acesso a múltiplos conectores (pesquisa, sistema de arquivos)
• O ambiente Runlayer é necessário para pesquisas GitHub e Jira
• A qualidade da saída depende diretamente da qualidade das fontes encontradas
• Sempre solicitar confirmação explícita do usuário antes de gerar qualquer documento
• Manter o tom profissional e objetivo em todos os documentos gerados