claude-plugins/gestao/skills/doc-coauthoring/SKILL.md

name, description

name	description
doc-coauthoring	Workflow estruturado para co-autoria de documentos. Usar quando o utilizador quer escrever propostas comerciais, specs de projecto, relatórios cliente, SOPs, decisões técnicas ou conteúdo estruturado. Guia 3 fases - recolha de contexto, refinamento iterativo e teste de leitura. Trigger quando "escrever doc", "redigir proposta", "criar spec", "documentar", "relatório", "SOP".

/doc-coauthoring - Co-Autoria de Documentos

Workflow estruturado para criação colaborativa de documentos profissionais. Guia o utilizador por três fases: recolha de contexto, refinamento e teste de leitura.

Arquitectura

Pedido → Fase 1 (Contexto) → Fase 2 (Refinamento) → Fase 3 (Teste Leitura) → Documento Final
              ↓                      ↓                        ↓
         /knowledge              Templates Hub            Sub-agente leitor
         /crm (dados cliente)    Iteração secção a secção  Detecta pontos cegos

---

Quando Activar

Condições de trigger:

• Utilizador menciona escrita de documentação: "escrever doc", "redigir proposta", "criar spec", "documentar"
• Utilizador menciona tipos específicos: "proposta comercial", "spec de projecto", "relatório cliente", "SOP", "decisão técnica", "RFC"
• Utilizador inicia uma tarefa de escrita substancial

Tipos de documento suportados:

Tipo	Template Hub	Notas
Proposta comercial	Hub/90-Templates/Comercial/	Integrar dados cliente via /crm
Spec de projecto	Hub/90-Templates/TPL-Projecto/	Incluir arquitectura, milestones
Relatório cliente	Hub/90-Templates/	Dados do Desk CRM
SOP / Procedimento	Hub/06-Operacoes/Procedimentos/	Formato PROC-*.md
Decisão técnica	—	Registar contexto e alternativas
RFC / Design doc	—	Foco em trade-offs e impacto

Oferta inicial: Oferecer ao utilizador um workflow estruturado para co-autoria. Explicar as três fases:

1. Recolha de contexto: O utilizador fornece todo o contexto relevante enquanto são feitas perguntas de clarificação
2. Refinamento e estrutura: Construção iterativa de cada secção através de brainstorming e edição
3. Teste de leitura: Testar o documento com um Claude sem contexto para detectar pontos cegos antes de outros lerem

Explicar que esta abordagem garante que o documento funciona quando outros o lêem. Perguntar se preferem este workflow ou trabalhar em formato livre.

Se o utilizador recusar, trabalhar em formato livre. Se aceitar, avançar para a Fase 1.

---

Fase 1: Recolha de Contexto

Objectivo: Fechar a lacuna entre o que o utilizador sabe e o que o Claude sabe, permitindo orientação inteligente depois.

Perguntas Iniciais

Começar por pedir meta-contexto sobre o documento:

1. Que tipo de documento é? (ex.: proposta comercial, spec de projecto, SOP)
2. Quem é o público-alvo principal?
3. Qual o impacto desejado quando alguém lê isto?
4. Existe um template ou formato específico a seguir?
5. Há algum cliente ou projecto associado? (para consultar /crm)
6. Outras restrições ou contexto relevante?

Informar que podem responder de forma breve ou despejar informação como preferirem.

Se o utilizador mencionar um template ou tipo de documento:

• Verificar templates disponíveis em Hub/90-Templates/
• Se mencionarem um template específico, usar filesystem para o ler
• Se mencionarem um documento partilhado (Google Drive, etc.), usar a integração adequada

Se o utilizador mencionar um cliente ou projecto:

• Usar /crm para obter dados do cliente (contactos, historial, projectos activos)
• Consultar Hub/07-Clientes/ para contexto adicional
• Verificar propostas anteriores em Hub/03-Propostas/ ou no Desk CRM

Se o utilizador mencionar edição de documento existente:

• Usar a integração adequada para ler o estado actual
• Verificar imagens sem alt-text
• Se existirem imagens sem alt-text, explicar que quando outros usarem o Claude para entender o documento, o Claude não consegue vê-las. Perguntar se querem alt-text gerado.

Despejo de Informação

Após as perguntas iniciais, encorajar o utilizador a despejar todo o contexto disponível. Pedir informação como:

• Background do projecto/problema
• Discussões de equipa ou documentos relacionados
• Porquê alternativas não estão a ser usadas
• Contexto organizacional (dinâmicas de equipa, incidentes passados)
• Pressões de prazo ou restrições
• Arquitectura técnica ou dependências
• Preocupações de stakeholders
• Dados do CRM relevantes (historial do cliente, propostas anteriores)

Aconselhar a não se preocuparem com organização — apenas tirar tudo cá para fora. Oferecer múltiplas formas de fornecer contexto:

• Despejo de informação em fluxo de consciência
• Apontar para canais ou threads de equipa
• Partilhar links para documentos

Pesquisa de contexto automática: Usar /knowledge para pesquisar contexto relevante nas fontes de conhecimento (NotebookLM, Supabase, docs locais). Informar o utilizador do que foi encontrado.

Se integrações disponíveis (Google Workspace, filesystem, etc.), mencionar que podem ser usadas para importar contexto directamente.

Durante a recolha de contexto:

• Se o utilizador mencionar canais ou documentos partilhados:

  • Se integrações disponíveis: Informar que o conteúdo será lido agora, depois usar a integração adequada
  • Se não disponíveis: Explicar falta de acesso. Sugerir que colem o conteúdo relevante directamente.

• Se o utilizador mencionar entidades/projectos desconhecidos:

  • Perguntar se devem ser pesquisados nas ferramentas conectadas
  • Aguardar confirmação antes de pesquisar

• À medida que o contexto é fornecido, acompanhar o que está a ser aprendido e o que ainda não é claro

Perguntas de clarificação:

Quando o utilizador sinalizar que terminou o despejo inicial (ou após contexto substancial), fazer perguntas de clarificação:

Gerar 5-10 perguntas numeradas baseadas nas lacunas do contexto.

Informar que podem usar taquigrafia para responder (ex.: "1: sim, 2: ver email X, 3: não por causa de compatibilidade"), apontar para mais docs, ou continuar a despejar. O que for mais eficiente.

Condição de saída: Contexto suficiente recolhido quando as perguntas demonstram compreensão — quando se consegue perguntar sobre casos extremos e trade-offs sem precisar de explicações básicas.

Transição: Perguntar se há mais contexto a fornecer, ou se é hora de avançar para a redacção.

Se quiserem adicionar mais, deixar. Quando prontos, avançar para a Fase 2.

---

Fase 2: Refinamento e Estrutura

Objectivo: Construir o documento secção a secção através de brainstorming, curadoria e refinamento iterativo.

Instruções ao utilizador: Explicar que o documento será construído secção a secção. Para cada secção:

1. Perguntas de clarificação sobre o que incluir
2. Brainstorming de 5-20 opções
3. O utilizador indica o que manter/remover/combinar
4. A secção é redigida
5. Refinamento através de edições cirúrgicas

Começar pela secção com mais incógnitas (normalmente a proposta/decisão central), depois trabalhar as restantes.

Ordenação de secções:

Se a estrutura do documento for clara: Perguntar por qual secção começar.

Sugerir começar pela secção com mais incógnitas. Para propostas comerciais, normalmente é o âmbito e preço. Para specs, é tipicamente a abordagem técnica. Secções de resumo ficam para o fim.

Se o utilizador não souber que secções precisa: Baseado no tipo de documento, template e contexto Descomplicar, sugerir 3-5 secções adequadas.

Sugestões por tipo de documento:

Tipo	Secções sugeridas
Proposta comercial	Contexto/Problema, Solução proposta, Âmbito e entregáveis, Investimento, Próximos passos
Spec de projecto	Objectivo, Arquitectura, Requisitos, Milestones, Riscos
Relatório cliente	Sumário executivo, Trabalho realizado, Métricas, Recomendações, Próximos passos
SOP	Objectivo, Pré-requisitos, Procedimento (passos), Verificação, Troubleshooting
Decisão técnica	Contexto, Opções avaliadas, Análise comparativa, Decisão, Consequências

Perguntar se a estrutura funciona ou se querem ajustá-la.

Quando a estrutura for acordada:

Criar a estrutura inicial do documento com texto placeholder para todas as secções.

Criar um ficheiro markdown no directório de trabalho. Nomear adequadamente (ex.: proposta-cliente-nome.md, spec-projecto.md).

Confirmar o nome do ficheiro criado e indicar que é hora de preencher cada secção.

Para cada secção:

Passo 1: Perguntas de Clarificação

Anunciar que o trabalho na secção [NOME DA SECÇÃO] vai começar. Fazer 5-10 perguntas de clarificação sobre o que incluir:

Gerar 5-10 perguntas específicas baseadas no contexto e objectivo da secção.

Informar que podem responder em taquigrafia ou apenas indicar o que é importante cobrir.

Passo 2: Brainstorming

Para a secção [NOME DA SECÇÃO], fazer brainstorming de [5-20] pontos que possam ser incluídos, dependendo da complexidade. Procurar:

• Contexto partilhado que possa ter sido esquecido
• Ângulos ou considerações ainda não mencionados
• Dados do /crm ou /knowledge relevantes

Gerar 5-20 opções numeradas baseadas na complexidade da secção. No fim, oferecer brainstorming adicional se quiserem mais opções.

Passo 3: Curadoria

Perguntar quais pontos manter, remover ou combinar. Pedir breves justificações para ajudar a aprender prioridades para as próximas secções.

Dar exemplos:

• "Manter 1,4,7,9"
• "Remover 3 (duplica o 1)"
• "Remover 6 (o público já sabe isto)"
• "Combinar 11 e 12"

Se o utilizador der feedback em formato livre (ex.: "está bom" ou "gosto da maioria mas...") em vez de selecções numeradas, extrair as preferências e prosseguir. Interpretar o que querem manter/remover/alterar e aplicar.

Passo 4: Verificação de Lacunas

Baseado no que seleccionaram, perguntar se falta algo importante para a secção [NOME DA SECÇÃO].

Passo 5: Redacção

Usar str_replace para substituir o texto placeholder desta secção pelo conteúdo redigido.

Anunciar que a secção [NOME DA SECÇÃO] vai ser redigida agora com base no que seleccionaram.

Após a redacção, confirmar conclusão. Informar que a secção [NOME DA SECÇÃO] foi redigida em [ficheiro]. Pedir que leiam e indiquem o que alterar. Notar que ser específico ajuda a aprender o estilo para futuras secções.

Instrução chave ao utilizador (incluir ao redigir a primeira secção): Nota: Em vez de editar o documento directamente, pedir que indiquem o que alterar. Isto ajuda a aprender o estilo para futuras secções. Exemplo: "Remover o bullet X — já coberto por Y" ou "Tornar o terceiro parágrafo mais conciso".

Passo 6: Refinamento Iterativo

À medida que o utilizador fornece feedback:

• Usar str_replace para fazer edições (nunca reimprimir todo o documento)
• Confirmar que as edições estão completas
• Se o utilizador editar o documento directamente e pedir para ler: notar mentalmente as alterações e tê-las em conta para futuras secções (revela preferências)

Continuar a iterar até o utilizador ficar satisfeito com a secção.

Verificação de Qualidade

Após 3 iterações consecutivas sem alterações substanciais, perguntar se algo pode ser removido sem perder informação importante.

Quando a secção estiver concluída, confirmar que [NOME DA SECÇÃO] está completa. Perguntar se estão prontos para a próxima secção.

Repetir para todas as secções.

Perto da Conclusão

Ao aproximar da conclusão (80%+ das secções feitas), anunciar intenção de reler todo o documento e verificar:

• Fluxo e consistência entre secções
• Redundância ou contradições
• Qualquer coisa que pareça genérico ou filler
• Se cada frase tem peso

Ler todo o documento e fornecer feedback.

Quando todas as secções estiverem redigidas e refinadas: Anunciar que todas as secções estão redigidas. Indicar intenção de rever o documento completo uma última vez.

Rever para coerência geral, fluxo, completude.

Fornecer sugestões finais.

Perguntar se estão prontos para o teste de leitura, ou se querem refinar mais alguma coisa.

---

Fase 3: Teste de Leitura

Objectivo: Testar o documento com um Claude sem contexto (sem contaminação) para verificar que funciona para leitores.

Instruções ao utilizador: Explicar que agora vai ser testado se o documento funciona para leitores. Isto detecta pontos cegos — coisas que fazem sentido para os autores mas podem confundir outros.

Abordagem de Teste

Se sub-agentes disponíveis (ex.: Claude Code):

Realizar o teste directamente sem envolvimento do utilizador.

Passo 1: Prever Perguntas dos Leitores

Anunciar intenção de prever que perguntas os leitores farão ao encontrar este documento.

Gerar 5-10 perguntas que leitores realisticamente fariam. Para documentos Descomplicar, incluir perguntas que um cliente ou parceiro faria.

Passo 2: Testar com Sub-Agente

Anunciar que estas perguntas vão ser testadas com uma instância Claude sem contexto desta conversa.

Para cada pergunta, invocar um sub-agente apenas com o conteúdo do documento e a pergunta.

Resumir o que o Claude leitor acertou/errou para cada pergunta.

Passo 3: Verificações Adicionais

Anunciar que verificações adicionais vão ser realizadas.

Invocar sub-agente para verificar ambiguidade, pressupostos falsos, contradições.

Resumir quaisquer problemas encontrados.

Passo 4: Reportar e Corrigir

Se problemas encontrados: Reportar que o Claude leitor teve dificuldades com questões específicas.

Listar os problemas específicos.

Indicar intenção de corrigir estas lacunas.

Voltar ao refinamento para secções problemáticas.

---

Se sub-agentes não disponíveis:

O utilizador terá de fazer o teste manualmente.

Passo 1: Prever Perguntas dos Leitores

Perguntar que perguntas as pessoas farão ao encontrar este documento. O que escreveriam no Claude.ai?

Gerar 5-10 perguntas que leitores realisticamente fariam.

Passo 2: Configurar Teste

Fornecer instruções de teste:

1. Abrir uma nova conversa Claude: https://claude.ai
2. Colar ou partilhar o conteúdo do documento
3. Fazer ao Claude leitor as perguntas geradas

Para cada pergunta, instruir o Claude leitor a fornecer:

• A resposta
• Se algo foi ambíguo ou pouco claro
• Que conhecimento/contexto o documento assume como conhecido

Verificar se o Claude leitor dá respostas correctas ou interpreta mal algo.

Passo 3: Verificações Adicionais

Também perguntar ao Claude leitor:

• "O que neste documento pode ser ambíguo ou pouco claro para leitores?"
• "Que conhecimento ou contexto este documento assume que os leitores já têm?"
• "Há contradições internas ou inconsistências?"

Passo 4: Iterar com Base nos Resultados

Perguntar o que o Claude leitor errou ou teve dificuldade. Indicar intenção de corrigir essas lacunas.

Voltar ao refinamento para secções problemáticas.

---

Condição de Saída (Ambas as Abordagens)

Quando o Claude leitor responde consistentemente às perguntas de forma correcta e não levanta novas lacunas ou ambiguidades, o documento está pronto.

---

Revisão Final

Quando o teste de leitura passar: Anunciar que o documento passou o teste de leitura. Antes de concluir:

1. Recomendar uma leitura final pelo utilizador — eles são donos do documento e responsáveis pela qualidade
2. Sugerir verificação dupla de factos, links ou detalhes técnicos
3. Perguntar se atinge o impacto desejado

Perguntar se querem mais uma revisão ou se o trabalho está concluído.

Se quiserem revisão final, fornecer. Caso contrário: Anunciar conclusão do documento. Fornecer dicas finais:

• Considerar gerar o documento final com /docx, /xlsx ou /pdf conforme o formato necessário
• Usar apêndices para fornecer profundidade sem inchar o documento principal
• Actualizar o documento à medida que feedback é recebido de leitores reais
• Se for proposta comercial, considerar criar estimate no Desk CRM via /crm

---

Integração com Ecossistema Descomplicar

Fontes de Contexto

Fonte	Quando usar	Como
/knowledge	Pesquisar conhecimento temático	NotebookLM, Supabase, docs locais
/crm	Dados de clientes e projectos	Desk CRM (contactos, historial, propostas)
Hub/90-Templates/	Templates de documentos	Estruturas predefinidas
Hub/03-Propostas/	Propostas anteriores	Referência de estilo e conteúdo
Hub/07-Clientes/	Contexto de clientes	Notas, projectos, ficheiros

Formatos de Saída

Após concluir o documento:

• Proposta comercial → /docx ou /pdf para envio ao cliente
• Spec de projecto → Manter como .md no directório do projecto
• SOP / Procedimento → Mover para Hub/06-Operacoes/Procedimentos/ como PROC-*.md
• Relatório cliente → /pdf para envio, guardar cópia em Hub/07-Clientes/
• Decisão técnica → Guardar em Supabase via /knowledge e no Hub

---

Dicas para Orientação Eficaz

Tom:

• Directo e procedimental
• Explicar brevemente o racional quando afecta o comportamento do utilizador
• Não tentar "vender" a abordagem — apenas executá-la

Lidar com Desvios:

• Se o utilizador quiser saltar uma fase: Perguntar se querem saltar e escrever em formato livre
• Se o utilizador parecer frustrado: Reconhecer que está a demorar mais do que esperado. Sugerir formas de acelerar
• Dar sempre agência ao utilizador para ajustar o processo

Gestão de Contexto:

• Ao longo de todo o processo, se faltar contexto sobre algo mencionado, perguntar proactivamente
• Não deixar lacunas acumular — resolvê-las à medida que surgem

Gestão de Ficheiros:

• Usar str_replace para todas as edições
• Confirmar edições após cada alteração
• Nunca usar brainstorming em ficheiros — isso é conversa
• Documento de trabalho sempre em markdown até formato final

Qualidade sobre Velocidade:

• Não apressar as fases
• Cada iteração deve trazer melhorias significativas
• O objectivo é um documento que funciona para leitores

---

Changelog

v1.0.0 (2026-03-06)

• Versão inicial adaptada de Anthropic doc-coauthoring
• Workflow de 3 fases: contexto, refinamento, teste de leitura
• Integração com /knowledge, /crm e templates Hub
• Tipos de documento Descomplicar: propostas, specs, relatórios, SOPs
• Sugestões de secções por tipo de documento
• Formatos de saída com /docx, /xlsx, /pdf
• Integração com ecossistema Descomplicar (Desk CRM, Hub, templates)

---

Versão: 1.0.0 | Data: 2026-03-06 | Autor: Descomplicar®