--- name: doc-coauthoring description: 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®