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

---
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®