claude-plugins/gestao/skills/spec-coauthor/SKILL.md

---
name: spec-coauthor
description: Co-autoria iterativa de documentos estruturados — SPECs de projecto, propostas comerciais e PROCs operacionais. Workflow 3 fases com brainstorming, curadoria e teste de leitura por sub-agente. Usar quando "spec", "proposta", "PROC", "documento", "co-autoria", "redigir", "estruturar documento", "escrever proposta".
---

# /spec-coauthor - Co-Autoria de Documentos Estruturados

Co-autoria iterativa de SPECs, propostas comerciais e PROCs operacionais com workflow de 3 fases: recolha de contexto, refinamento estruturado e teste de leitura.

---

## Tipos de Documento Suportados

| Tipo | Audiência | Exemplos |
|------|-----------|----------|
| **SPEC de projecto** | Equipa técnica, Emanuel | WhatSMS-v2-SPEC.md, DashDescomplicar-SPEC.md |
| **Proposta comercial** | Cliente, stakeholders | Proposta-ClienteX-SEO.md, Proposta-ERP-2026.md |
| **PROC operacional** | Equipa interna, ops | PROC-Deploy-EasyPanel.md, PROC-Onboarding-Cliente.md |

---

## Fase 1: Recolha de Contexto

### 1.1 Identificar tipo de documento

Perguntar ao utilizador:

```
1. Que tipo de documento precisas criar?
   a) SPEC de projecto (requisitos, arquitectura, milestones)
   b) Proposta comercial (solução, pricing, timeline)
   c) PROC operacional (passos, checklist, troubleshooting)
   d) Outro (descrever)

2. Para quem é este documento?
   - Emanuel (uso interno / decisão)
   - Cliente (venda / aprovação)
   - Equipa técnica (execução)
   - Múltiplas audiências (especificar)

3. Qual o impacto esperado?
   - Aprovar orçamento / go-ahead
   - Alinhar equipa em requisitos
   - Documentar processo para replicar
   - Outro (especificar)
```

### 1.2 Recolher contexto existente

Após identificar tipo e audiência, recolher contexto via:

**Desk CRM:**
```
mcp__desk-crm-v3__get_projects → projectos activos relacionados
mcp__desk-crm-v3__get_tasks    → tarefas e sub-tarefas relevantes
mcp__desk-crm-v3__get_customers → dados do cliente (se proposta)
```

**Hub / Ficheiros:**
```
Read ficheiros relevantes em:
  /media/ealmeida/Dados/Hub/05-Projectos/[projecto]/
  /media/ealmeida/Dados/Hub/07-Clientes/[cliente]/
  /media/ealmeida/Dados/Hub/90-Templates/
```

**Perguntas complementares de contexto:**
```
4. Existe documentação anterior? (SPEC, proposta, email, notas)
   → Partilhar caminho ou colar conteúdo

5. Há restrições ou requisitos não-negociáveis?
   → Prazo, orçamento, tecnologia obrigatória

6. Qual o nível de detalhe desejado?
   → Resumo executivo (1-2 pág.) / Documento completo (5-15 pág.) / Ultra-detalhado
```

### 1.3 Confirmar antes de avançar

Apresentar resumo do contexto recolhido e confirmar com utilizador antes de passar à Fase 2.

```
**Contexto confirmado:**
- Tipo: [SPEC / Proposta / PROC]
- Audiência: [quem vai ler]
- Impacto: [decisão esperada]
- Referências encontradas: [ficheiros / tarefas]
- Nível de detalhe: [resumo / completo / ultra]

Avançar para estruturação? (s/n)
```

---

## Fase 2: Refinamento e Estrutura

### 2.1 Brainstorming de secções

Para cada secção principal do documento, gerar **5 a 20 opções** de abordagem/conteúdo.

**Formato de apresentação:**

```
## Secção: [Nome da Secção]

Opções de abordagem:

1. [Opção concisa — 1 linha de descrição]
2. [Opção alternativa]
3. [Opção mais detalhada]
4. [Opção focada em audiência técnica]
5. [Opção focada em audiência não técnica]
...

→ Quais queres manter? (ex: "1,3,5" ou "todas" ou "nenhuma, tentar de novo")
```

**Regras do brainstorming:**
- Apresentar opções reais e diferenciadas (não variações mínimas)
- Indicar vantagens de cada abordagem em 1 linha
- Nunca gerar menos de 5 opções por secção
- Para SPECs técnicas: incluir sempre opção de maior e menor detalhe
- Para propostas: incluir sempre opção orientada a valor e a custo

### 2.2 Curadoria pelo utilizador

O utilizador selecciona opções com sintaxe simples:

```
"Keep 1,4,7"     → manter apenas essas opções
"Todas"          → aceitar todas
"Nenhuma"        → tentar de novo com abordagem diferente
"1 mas mais curto" → manter com refinamento
"Combinar 2 e 5" → fusão das opções
```

### 2.3 Drafting iterativo

Após curadoria de cada secção, produzir rascunho com `str_replace_editor` ou apresentar em bloco markdown.

**Ciclo por secção:**
```
1. Brainstorm (5-20 opções)
2. Curadoria pelo utilizador
3. Draft da secção
4. Revisão inline ("mudar X para Y" / "expandir parágrafo Z")
5. Confirmar → avançar para secção seguinte
```

**Ordem de secções por tipo:**

Para SPEC de projecto:
```
1. Contexto e problema
2. Objectivo e scope
3. Requisitos funcionais
4. Requisitos técnicos / arquitectura
5. Milestones e timeline
6. Riscos e dependências
7. Definition of Done
8. Referências
```

Para proposta comercial:
```
1. Sumário executivo
2. Contexto e diagnóstico
3. Solução proposta
4. Entregáveis e timeline
5. Investimento e condições
6. Próximos passos
7. Sobre a Descomplicar
```

Para PROC operacional:
```
1. Objectivo e âmbito
2. Pré-requisitos
3. Passos detalhados
4. Checklist de execução
5. Troubleshooting
6. Métricas e validação
7. Referências cruzadas
```

### 2.4 Revisão global

Após completar todas as secções:

```
Documento completo em rascunho. Revisão global:

1. Fluxo lógico entre secções ✓/✗
2. Consistência de terminologia ✓/✗
3. Nível de detalhe adequado à audiência ✓/✗
4. Sem lacunas de informação crítica ✓/✗

Ajustes antes do teste de leitura? (s/n)
```

---

## Fase 3: Teste de Leitura

### 3.1 Sub-agente "leitor fresco"

Invocar sub-agente via Agent tool **sem fornecer contexto da sessão actual**. O sub-agente recebe apenas o documento final e responde como leitor novo.

**Instrução para o sub-agente:**

```
És um leitor que vê este documento pela primeira vez.
Não tens contexto adicional sobre o projecto ou empresa.
Lê o documento abaixo e responde:

1. O que este documento comunica? (resumo em 2-3 frases)
2. Quem é a audiência alvo?
3. Que perguntas ficaram sem resposta?
4. Há algum ponto confuso ou contraditório?
5. O que mudarias na estrutura ou linguagem?

DOCUMENTO:
[colar documento completo]
```

### 3.2 Análise das lacunas detectadas

Apresentar ao utilizador o relatório do sub-agente:

```
**Relatório do leitor fresco:**

Compreensão: [resumo do sub-agente]
Audiência identificada: [o sub-agente identificou correctamente?]

Lacunas detectadas:
- [Lacuna 1]
- [Lacuna 2]

Confusões detectadas:
- [Ponto X não está claro]

Sugestões estruturais:
- [Sugestão A]
```

### 3.3 Correcção iterativa

Para cada lacuna ou confusão, propor correcção:

```
Lacuna: "Não fica claro qual o prazo de entrega"
Proposta: Adicionar secção "Timeline" com datas concretas
→ Aprovar correcção? (s/n)
```

Repetir Fase 3 se correcções forem substanciais.

---

## Integração com Desk CRM

### Criar/actualizar tarefa associada

Após finalizar o documento:

```
mcp__desk-crm-v3__create_task ou update_task:
  - Nome: "SPEC/Proposta/PROC: [Título documento]"
  - Descrição: Sumário do documento
  - Projecto: [projecto associado]
  - Status: Em revisão / Concluído
```

### Comentário HTML na tarefa

```html
<h4>Documento criado</h4>
<ul>
  <li>Tipo: [SPEC / Proposta / PROC]</li>
  <li>Audiência: [quem vai ler]</li>
  <li>Fases concluídas: Context Gathering → Refinamento → Teste de Leitura</li>
</ul>
<p><strong>Ficheiro:</strong> <code>[path absoluto do documento]</code></p>
<hr>
<p><strong>Skill:</strong> /spec-coauthor | <strong>Data:</strong> YYYY-MM-DD</p>
```

---

## Onde Guardar o Documento

| Tipo | Destino |
|------|---------|
| SPEC de projecto | `/media/ealmeida/Dados/Hub/05-Projectos/[projecto]/` |
| Proposta comercial | `/media/ealmeida/Dados/Hub/03-Propostas/` |
| PROC operacional | `/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/[Dept]/` |
| Rascunho/inbox | `/media/ealmeida/Dados/Hub/00-Inbox/` |

**Nomeação de ficheiros:**
- SPEC: `[Projecto]-SPEC.md` ou `[Projecto]-SPEC-v2.md`
- Proposta: `Proposta-[Cliente]-[Tema]-YYYY-MM-DD.md`
- PROC: `PROC-[Título].md` (via `/proc-creator` para código correcto)

---

## Referências e Templates

**Templates detalhados:** `references/templates.md` (neste directório)
- Template SPEC completo
- Template proposta comercial
- Template PROC operacional

**Skills relacionadas:**
- `/proc-creator` — Criar PROCs com código departamental correcto e actualizar INDEX.md
- `/orcamento` — Gerar orçamentos e propostas com pricing
- `/knowledge` — Pesquisar contexto em NotebookLM / Hub antes de redigir

---

## Anti-Patterns

**Nunca:**
- Redigir documento completo de uma vez sem curadoria por secção
- Avançar para Fase 3 sem aprovação do rascunho completo
- Fornecer contexto da sessão ao sub-agente de teste
- Guardar documento sem tarefa Desk CRM associada
- Usar emojis ou maiúsculas desnecessárias no documento

**Sempre:**
- Confirmar audiência antes de escolher linguagem e detalhe
- Gerar mínimo 5 opções por secção de brainstorming
- Aguardar curadoria do utilizador antes de rascunhar
- Corrigir lacunas detectadas pelo leitor fresco antes de fechar
- PT-PT estrito em todo o documento gerado

---

*Skill v1.0.0 | 2026-03-10 | Plugin gestao | Descomplicar®*