# Templates spec-coauthor

Templates de referência para os três tipos de documento suportados pela skill /spec-coauthor.

---

## Template 1: SPEC de Projecto

```markdown
---
title: [Nome do Projecto] — SPEC
date: YYYY-MM-DD
type: spec
status: draft
version: 1.0
projecto_desk_id: [ID Desk CRM]
tags: [spec, projecto, tecnologia]
---

# [Nome do Projecto] — Especificação Técnica

**Versão:** 1.0 | **Data:** YYYY-MM-DD | **Status:** Draft
**Autor:** Emanuel Almeida | **Revisão:** [nome revisor]

---

## 1. Contexto e Problema

### 1.1 Contexto actual

Descrição do estado actual do sistema/processo que este projecto vai resolver ou melhorar.

### 1.2 Problema identificado

Descrição clara e específica do problema. Incluir:
- Impacto actual (tempo perdido, custo, risco)
- Frequência do problema
- Quem é afectado

### 1.3 Oportunidade

O que se torna possível ao resolver este problema.

---

## 2. Objectivo e Scope

### 2.1 Objectivo principal

Uma frase clara do que este projecto entrega.

### 2.2 Scope incluído

- [Feature ou entregável 1]
- [Feature ou entregável 2]
- [Feature ou entregável 3]

### 2.3 Scope excluído (fora de scope)

- [Item explicitamente excluído 1]
- [Item explicitamente excluído 2]

### 2.4 Critérios de sucesso

| Critério | Medição | Target |
|----------|---------|--------|
| [Critério 1] | [Como medir] | [Valor] |
| [Critério 2] | [Como medir] | [Valor] |

---

## 3. Requisitos Funcionais

### 3.1 [Módulo ou área funcional A]

| ID | Requisito | Prioridade | Notas |
|----|-----------|------------|-------|
| RF-001 | [Descrição] | Must / Should / Could | [Detalhe] |
| RF-002 | [Descrição] | Must / Should / Could | [Detalhe] |

### 3.2 [Módulo ou área funcional B]

| ID | Requisito | Prioridade | Notas |
|----|-----------|------------|-------|
| RF-010 | [Descrição] | Must / Should / Could | [Detalhe] |

---

## 4. Requisitos Técnicos e Arquitectura

### 4.1 Stack tecnológico

| Camada | Tecnologia | Justificação |
|--------|------------|-------------|
| Frontend | [ex: Next.js 14] | [razão] |
| Backend | [ex: Laravel 11] | [razão] |
| Base de dados | [ex: MySQL 8] | [razão] |
| Infra | [ex: EasyPanel + CWP] | [razão] |

### 4.2 Diagrama de arquitectura

```
[Componente A] → [API] → [Componente B]
                            ↓
                      [Base de dados]
```

### 4.3 Integrações externas

| Sistema | Tipo integração | Dados trocados | Responsável |
|---------|----------------|----------------|-------------|
| [Sistema X] | REST API | [dados] | [quem] |
| [Sistema Y] | Webhook | [eventos] | [quem] |

### 4.4 Requisitos não-funcionais

| Requisito | Descrição | Target |
|-----------|-----------|--------|
| Performance | Tempo resposta API | < 500ms (p95) |
| Disponibilidade | Uptime | 99.5% |
| Segurança | Autenticação | JWT + refresh tokens |
| Escalabilidade | [detalhe] | [target] |

---

## 5. Milestones e Timeline

| Milestone | Entregável | Data alvo | Dependências |
|-----------|-----------|-----------|-------------|
| M1 — Setup | Infra + repo configurado | YYYY-MM-DD | — |
| M2 — MVP | [Feature core] funcional | YYYY-MM-DD | M1 |
| M3 — Beta | Testes com utilizadores | YYYY-MM-DD | M2 |
| M4 — Launch | Deploy produção | YYYY-MM-DD | M3 |

**Estimativa total:** [X semanas / meses]
**Velocidade estimada:** [X story points/sprint]

---

## 6. Riscos e Dependências

| Risco | Probabilidade | Impacto | Mitigação |
|-------|---------------|---------|-----------|
| [Risco 1] | Alta / Média / Baixa | Alto / Médio / Baixo | [acção] |
| [Risco 2] | Alta / Média / Baixa | Alto / Médio / Baixo | [acção] |

**Dependências bloqueantes:**
- [Dependência externa 1 — quem / quando]
- [Dependência externa 2 — quem / quando]

---

## 7. Definition of Done

Uma user story / feature é considerada concluída quando:

- [ ] Código em PR aprovado por pelo menos 1 revisor
- [ ] Testes unitários escritos (cobertura > X%)
- [ ] Testes de integração passam em CI
- [ ] Documentação actualizada
- [ ] Sem issues críticas em `pnpm audit`
- [ ] Deploy em staging testado e aprovado
- [ ] Tarefa Desk CRM actualizada com comentário HTML

---

## 8. Referências

**Projectos relacionados:**
- [Link para projecto Desk CRM]
- [Link para repositório Gitea]

**Documentação técnica:**
- [Link para API externa]
- [Link para PROC relevante]

**Ficheiros relevantes:**
- `[path local do ficheiro]`

---

**[Nome do Projecto] SPEC v1.0 | YYYY-MM-DD | Descomplicar®**
```

---

## Template 2: Proposta Comercial

```markdown
---
title: Proposta — [Cliente] — [Tema]
date: YYYY-MM-DD
type: proposta
status: draft
cliente_desk_id: [ID Desk CRM]
validade: YYYY-MM-DD
valor_total: [X EUR]
tags: [proposta, cliente, tema]
---

# Proposta Comercial
## [Título do Serviço / Projecto]

**Para:** [Nome Cliente] | [NIF se disponível]
**De:** Descomplicar — Crescimento Digital | NIF: 514 785 691
**Data:** YYYY-MM-DD | **Válida até:** YYYY-MM-DD
**Referência:** PROP-[YYYY]-[NNN]

---

## 1. Sumário Executivo

[2-3 parágrafos que respondem a: qual é o problema do cliente, o que propomos, e qual o resultado esperado. Escrito para quem não vai ler o documento completo.]

**Em síntese:** [Uma frase que resume proposta e valor.]

---

## 2. Contexto e Diagnóstico

### 2.1 Situação actual

[Descrever o estado actual do cliente com base no que foi partilhado. Mostrar que compreendemos o negócio e os desafios.]

### 2.2 Oportunidade identificada

[O que está a ser perdido / o que pode ser ganho. Contextualizar o valor da solução.]

### 2.3 Objectivo do projecto

[O que o cliente vai conseguir após a conclusão. Focado em resultado de negócio, não em features técnicas.]

---

## 3. Solução Proposta

### 3.1 Abordagem

[Descrever a solução de forma clara e não técnica. Como vamos resolver o problema.]

### 3.2 Entregáveis

| # | Entregável | Descrição | Formato |
|---|-----------|-----------|---------|
| 1 | [Nome] | [O que é] | [ficheiro / deploy / formação] |
| 2 | [Nome] | [O que é] | [ficheiro / deploy / formação] |
| 3 | [Nome] | [O que é] | [ficheiro / deploy / formação] |

### 3.3 O que não está incluído

[Listar explicitamente o que está fora de scope para evitar mal-entendidos.]

- [Item excluído 1]
- [Item excluído 2]

---

## 4. Timeline e Fases

| Fase | Descrição | Duração | Entregável |
|------|-----------|---------|-----------|
| 1 — [Nome] | [Actividades] | [X dias/semanas] | [O quê] |
| 2 — [Nome] | [Actividades] | [X dias/semanas] | [O quê] |
| 3 — [Nome] | [Actividades] | [X dias/semanas] | [O quê] |

**Início estimado:** [data, condicionada a aprovação em X dias]
**Conclusão estimada:** [data]

**Condições de prazo:**
- [Condição 1 — ex: receber acessos até X]
- [Condição 2 — ex: feedback em até X dias úteis]

---

## 5. Investimento

### 5.1 Resumo de valores

| Serviço | Valor |
|---------|-------|
| [Fase 1 / componente 1] | [X EUR] |
| [Fase 2 / componente 2] | [X EUR] |
| [Manutenção mensal] | [X EUR/mês] |
| **Total projecto** | **[X EUR]** |

*Valores sem IVA. IVA à taxa legal em vigor (23%).*

### 5.2 Condições de pagamento

- [X]% na assinatura — [valor EUR]
- [X]% na entrega de [milestone] — [valor EUR]
- [X]% na conclusão e aprovação final — [valor EUR]

### 5.3 Validade da proposta

Esta proposta é válida até **[data]**. Após esta data os valores poderão ser revistos.

---

## 6. Próximos Passos

Para avançar com este projecto:

1. **Aprovação** — responder a este email com "aprovado" ou solicitar reunião para esclarecimentos
2. **Contrato** — envio de contrato para assinatura em [X dias úteis]
3. **Pagamento inicial** — processamento do primeiro pagamento
4. **Kickoff** — reunião de arranque em [X dias após pagamento]

**Contacto:** Emanuel Almeida | emanuel@descomplicar.pt | 911 510 005

---

## 7. Sobre a Descomplicar

A Descomplicar é uma empresa portuguesa especializada em crescimento digital para PMEs.

**O que fazemos:** Desenvolvimento web, automação de processos, integração de sistemas e consultoria digital.

**Experiência relevante:**
- [Projecto ou cliente relevante 1]
- [Projecto ou cliente relevante 2]

**Website:** descomplicar.pt | **NIF:** 514 785 691

---

*Proposta PROP-[YYYY]-[NNN] | [Cliente] | YYYY-MM-DD | Descomplicar®*
```

---

## Template 3: PROC Operacional

```markdown
---
title: [Título do Procedimento]
date: YYYY-MM-DD
type: procedimento
status: draft
dept_id: [1-7]
desk_dept_id: [1-7]
desk_dept_name: [D1-Comercial | ... | D7-Tecnologia | Cross-Departamental]
codigo: [DEPT]-[TEMA]-[NUM]
tags: [tag1, tag2, tag3]
---

# [Título do Procedimento]

**Código:** [DEPT]-[TEMA]-[NUM] | **Departamento:** [Nome] | **Status:** Draft
**Criado:** YYYY-MM-DD | **Revisão:** [data da próxima revisão]

---

## 1. Objectivo

[Uma ou duas frases que descrevem o que este procedimento permite fazer e qual o resultado esperado ao segui-lo.]

---

## 2. Âmbito

### Aplica-se a:
- [Situação ou contexto onde usar este PROC]
- [Quem executa este procedimento]
- [Frequência de execução]

### Não se aplica a:
- [Situação excluída — e qual PROC usar em alternativa]

---

## 3. Pré-requisitos

| Requisito | Descrição | Como verificar |
|-----------|-----------|----------------|
| [Acesso X] | [Para quê] | [Onde confirmar] |
| [Ferramenta Y] | [Versão mínima] | [Comando de verificação] |
| [Conhecimento Z] | [Nível esperado] | [PROC ou doc de referência] |

---

## 4. Procedimento

### Passo 1: [Nome descritivo do passo]

**Objectivo:** [O que se consegue neste passo]

**Acções:**
1. [Acção concreta com comando se aplicável]
2. [Acção seguinte]
3. [Acção final do passo]

**Exemplo:**
```bash
# Comando de exemplo (se técnico)
exemplo-comando --opcao valor
```

**Validação:** [Como confirmar que este passo foi bem-sucedido]

---

### Passo 2: [Nome descritivo do passo]

**Objectivo:** [O que se consegue neste passo]

**Acções:**
1. [Acção concreta]
2. [Acção seguinte]

**Validação:** [Como confirmar sucesso]

---

### Passo 3: [Nome descritivo do passo]

[...]

---

## 5. Checklist de Execução

Usar para confirmar cada passo antes de avançar:

- [ ] Pré-requisitos verificados
- [ ] Passo 1 concluído e validado
- [ ] Passo 2 concluído e validado
- [ ] Passo 3 concluído e validado
- [ ] Resultado final validado
- [ ] Tarefa Desk CRM actualizada (se aplicável)
- [ ] Comentário HTML adicionado (se aplicável)

---

## 6. Troubleshooting

| Problema | Causa provável | Solução | Escalação |
|----------|----------------|---------|-----------|
| [Erro ou situação X] | [Porquê acontece] | [Passos para resolver] | [Quem contactar se não resolver] |
| [Erro ou situação Y] | [Porquê acontece] | [Passos para resolver] | [Quem contactar] |

---

## 7. Métricas e Validação

| Métrica | O que mede | Target | Como medir |
|---------|------------|--------|------------|
| [Tempo de execução] | Eficiência do processo | < [X min] | Cronometrar na primeira execução |
| [Taxa de sucesso] | Fiabilidade | > [X%] | Registo de execuções |

---

## 8. Referências Cruzadas

**Procedimentos relacionados:**
- [PROC-Outro.md](../PROC-Outro.md) — [Quando usar em vez deste]
- [PROC-Dependente.md](../PROC-Dependente.md) — [Executar antes/depois]

**Skills relacionadas:**
- `/skill-name` — [Para que serve em relação a este PROC]

**Documentação externa:**
- [Nome da doc](URL) — [O que cobre]

**Quick Reference:**
- `Hub/06-Operacoes/Documentacao/Quick-Reference/QR-[Tema].md`

---

## 9. Histórico de Revisões

| Data | Versão | Autor | Alterações |
|------|--------|-------|------------|
| YYYY-MM-DD | 1.0 | Emanuel Almeida | Criação inicial |

---

**[Título] | Código: [DEPT]-[TEMA]-[NUM] | [Departamento]**
**Última actualização:** YYYY-MM-DD
```

---

*Templates spec-coauthor v1.0.0 | 2026-03-10 | Plugin gestao | Descomplicar®*