/cs-kb-article

name: cs-kb-article
description: Redige um artigo para base de conhecimento a partir de um problema resolvido ou pergunta frequente. Use quando a resolução de um ticket vale ser documentada para self-service, a mesma pergunta continua aparecendo, um workaround precisa ser publicado, ou um problema conhecido deve ser comunicado aos clientes. / Draft a knowledge base article from a resolved issue or common question. Use when a ticket resolution is worth documenting for self-service, the same question keeps coming up, a workaround needs to be published, or a known issue should be communicated to customers.
argument-hint: "<problema resolvido ou ticket>"

/cs-kb-article

> Se encontrar integrações não configuradas, verifique [CONNECTORS.md](../../CONNECTORS.md).

Redigir um artigo de base de conhecimento pronto para publicação a partir de um problema de suporte resolvido, pergunta frequente ou workaround documentado. Estrutura o conteúdo para pesquisabilidade e self-service.

Usage

/cs-kb-article <problema resolvido, referência de ticket ou descrição do tópico>

Exemplos:

• `/cs-kb-article Como configurar SSO com Okta — resolvi isso para 3 clientes no mês passado`
• `/cs-kb-article Ticket #4521 — cliente não conseguia exportar dados com mais de 10k linhas`
• `/cs-kb-article Pergunta frequente: como configurar notificações via webhook`
• `/cs-kb-article Problema conhecido: gráficos do dashboard não carregam no Safari 16`

Workflow

1. Entender o Material Fonte

Analisar o input para identificar:

• **Qual foi o problema?** O problema original, pergunta ou erro
• **Qual foi a solução?** A resolução, workaround ou resposta
• **Quem é afetado?** Tipo de usuário, nível de plano ou configuração
• **Qual é a frequência?** Problema único ou recorrente
• **Qual tipo de artigo se encaixa melhor?** How-to, troubleshooting, FAQ, problema conhecido ou referência (ver tipos de artigo abaixo)

Se uma referência de ticket for fornecida, buscar o contexto completo:

• **int-evo-crm** (`/int-evo-crm`): Puxar o thread do ticket, resolução e quaisquer notas internas
• **Notion MCP**: Verificar se um artigo similar já existe (atualizar vs. criar novo)
• **int-linear-review** (`/int-linear-review`) ou **Linear MCP**: Verificar se há bug report ou feature request relacionado

2. Redigir o Artigo

Usando a estrutura de artigo, padrões de formatação e boas práticas de pesquisabilidade abaixo:

• Seguir o template para o tipo de artigo escolhido (how-to, troubleshooting, FAQ, problema conhecido ou referência)
• Aplicar as boas práticas de pesquisabilidade: título em linguagem do cliente, frase de abertura em linguagem simples, mensagens de erro exatas, sinônimos comuns
• Manter escaneável: headers, passos numerados, parágrafos curtos

3. Gerar o Artigo

Apresentar o rascunho com metadados:

## Rascunho de Artigo KB

**Título:** [Título do artigo]
**Tipo:** [How-to / Troubleshooting / FAQ / Problema Conhecido / Referência]
**Categoria:** [Área de produto ou tópico]
**Tags:** [Tags pesquisáveis]
**Público:** [Todos os usuários / Admins / Desenvolvedores / Plano específico]

---

[Conteúdo completo do artigo — usando o template apropriado abaixo]

---

### Notas de Publicação
- **Fonte:** [Ticket #, conversa com cliente, ou discussão interna]
- **Artigos existentes para atualizar:** [Se isso tem sobreposição com conteúdo existente]
- **Revisão necessária de:** [SME ou time se precisar verificar precisão técnica]
- **Data de revisão sugerida:** [Quando revisitar para verificar precisão]

4. Oferecer Próximos Passos

Após gerar o artigo:

• "Quer que eu verifique se um artigo similar já existe no Notion?"
• "Devo ajustar a profundidade técnica para um público diferente?"
• "Quer que eu redija um artigo complementar (ex: um how-to para acompanhar este guia de troubleshooting)?"
• "Devo criar uma versão apenas interna com detalhes técnicos adicionais?"

---

Estrutura de Artigo e Padrões de Formatação

Elementos Universais de Artigo

Todo artigo KB deve incluir:

1. **Título**: Claro, pesquisável, descreve o resultado ou problema (não jargão interno) 2. **Overview**: 1-2 frases explicando o que o artigo cobre e para quem é 3. **Corpo**: Conteúdo estruturado adequado ao tipo de artigo 4. **Artigos relacionados**: Links para conteúdo complementar relevante 5. **Metadados**: Categoria, tags, público, data da última atualização

Regras de Formatação

• **Usar headers (H2, H3)** para dividir o conteúdo em seções escaneáveis
• **Usar listas numeradas** para passos sequenciais
• **Usar listas de bullets** para itens não sequenciais
• **Usar negrito** para nomes de elementos de UI, termos-chave e ênfase
• **Usar blocos de código** para comandos, chamadas de API, mensagens de erro e valores de configuração
• **Usar tabelas** para comparações, opções ou dados de referência
• **Usar callouts/notas** para avisos, dicas e ressalvas importantes
• **Manter parágrafos curtos** — 2-4 frases no máximo
• **Uma ideia por seção** — se uma seção cobre dois tópicos, dividir

Escrevendo para Pesquisabilidade

Artigos são inúteis se os clientes não conseguem encontrá-los. Otimizar cada artigo para busca:

Boas Práticas de Título

| Bom Título | Título Ruim | Por quê | |------------|-----------|-----| | "Como configurar SSO com Okta" | "Configuração SSO" | Específico, inclui o nome da ferramenta que clientes buscam | | "Fix: Dashboard mostra página em branco" | "Problema no Dashboard" | Inclui o sintoma que os clientes vivenciam | | "Rate limits e quotas da API" | "Informações da API" | Inclui os termos específicos que clientes buscam | | "Erro: 'Connection refused' ao importar dados" | "Problemas de Importação" | Inclui a mensagem de erro exata |

Otimização de Palavras-Chave

• **Incluir mensagens de erro exatas** — clientes copiam e colam texto de erro na busca
• **Usar linguagem do cliente**, não terminologia interna — "não consigo fazer login" não "falha de autenticação"
• **