# Padrões de Workflow para Skills

## Sumário

1. Workflows Sequenciais
2. Workflows Condicionais
3. Workflow Completo de Criação de Skill Descomplicar
4. Checklist de Entrega Final

---

## 1. Workflows Sequenciais

Para tarefas complexas, dividir operações em passos claros e sequenciais. É útil dar ao agente uma visão geral do processo no início do SKILL.md:

```markdown
Preencher um formulário PDF envolve estes passos:

1. Analisar o formulário (executar analyze_form.py)
2. Criar mapeamento de campos (editar fields.json)
3. Validar mapeamento (executar validate_fields.py)
4. Preencher o formulário (executar fill_form.py)
5. Verificar output (executar verify_output.py)
```

### Características de um bom workflow sequencial

- Cada passo é concreto e verificável
- Dependências entre passos são explícitas
- Artefactos de cada passo estão identificados
- Passos opcionais estão claramente marcados

---

## 2. Workflows Condicionais

Para tarefas com lógica de ramificação, guiar o agente pelos pontos de decisão:

```markdown
1. Determinar o tipo de modificação:
   **Criar novo conteúdo?** -> Seguir "Workflow de criação" abaixo
   **Editar conteúdo existente?** -> Seguir "Workflow de edição" abaixo

2. Workflow de criação:
   a. [passo 1]
   b. [passo 2]

3. Workflow de edição:
   a. [passo 1]
   b. [passo 2]
```

### Árvore de decisão para tipo de skill

Ao criar uma nova skill, determinar primeiro o tipo:

```
Skill nova ou actualização?
├── Nova skill
│   ├── Tem scripts reutilizáveis? -> incluir scripts/
│   ├── Tem docs de referência detalhadas? -> incluir references/
│   └── Tem templates/assets de output? -> incluir assets/
└── Actualização de skill existente
    ├── SKILL.md está >500 linhas? -> mover conteúdo para references/
    ├── Description é vaga? -> melhorar com triggers explícitos
    └── Há duplicação SKILL.md / references? -> consolidar
```

---

## 3. Workflow Completo de Criação de Skill Descomplicar

### Fase 1: Preparação (antes de escrever qualquer ficheiro)

```
1. Clarificar com o utilizador:
   - Que tarefas concretas a skill executa?
   - Que diria o utilizador para activar a skill?
   - Que conhecimento o agente não tem por defeito?

2. Identificar recursos reutilizáveis:
   - Código que é reescrito repetidamente -> scripts/
   - Docs de referência, schemas, APIs -> references/
   - Templates, assets de output -> assets/

3. Escolher o plugin de destino:
   - dev-tools: skills de desenvolvimento (PHP, JS, DB, segurança)
   - gestao: skills operacionais (worklog, desk, today)
   - crm-ops: skills comerciais (orçamento, leads)
   - core-tools: skills core do sistema
```

### Fase 2: Estrutura

```
4. Criar directório da skill:
   ~/.claude/plugins/cache/descomplicar-plugins/<plugin>/1.0.0/skills/<nome>/

5. Criar SKILL.md com:
   - Frontmatter: name + description (com triggers explícitos)
   - Corpo: workflow core, <500 linhas
   - Referencias a ficheiros de references/ (quando e por quê)

6. Criar references/ se necessário:
   - Um ficheiro por domínio/tema
   - Incluir índice no topo se >100 linhas
   - Sem duplicação com SKILL.md
```

### Fase 3: Validação

```
7. Verificar checklist de qualidade:
   [ ] Frontmatter: apenas name + description
   [ ] Description: triggers explícitos incluídos
   [ ] Corpo SKILL.md: <500 linhas
   [ ] Sem secção "Quando Usar" no corpo
   [ ] References documentadas com contexto sobre quando ler
   [ ] PT-PT estrito (verificar acentuação e vocabulário)
   [ ] Sem emojis nos ficheiros
   [ ] Sem ficheiros auxiliares (README, CHANGELOG, etc.)
   [ ] Graus de liberdade calibrados ao risco
   [ ] Assinatura Descomplicar® no código (se aplicável)

8. Empacotar (se scripts disponíveis):
   python scripts/package_skill.py <path/para/skill>
```

### Fase 4: Iteração

```
9. Testar em uso real:
   - Activar a skill numa tarefa real
   - Notar onde o agente hesita ou erra
   - Identificar informação em falta ou excessiva

10. Actualizar baseado em feedback:
    - Se o agente pede informação -> adicionar a references/
    - Se o agente ignora informação -> remover ou mover para references/
    - Se a skill activa nos momentos errados -> refinar description
```

---

## 4. Checklist de Entrega Final

Antes de considerar uma skill completa, validar:

### Frontmatter
- [ ] Apenas `name` e `description` (sem campos extra não documentados)
- [ ] `description` inclui o domínio e tecnologias principais
- [ ] `description` inclui triggers explícitos ("Usar quando...")
- [ ] `description` lista casos de uso concretos numerados

### Corpo SKILL.md
- [ ] Abaixo de 500 linhas (contar com `wc -l SKILL.md`)
- [ ] Sem secção "Quando Usar" no corpo
- [ ] References documentadas: nome do ficheiro + quando ler
- [ ] Forma imperativa/infinitivo nas instruções
- [ ] Sem emojis

### Língua e estilo
- [ ] PT-PT estrito (verificar: utilizador, palavra-passe, eliminar, calendarizar)
- [ ] Acentuação correcta (verificar: descrição, criação, configuração, autenticação)
- [ ] Monetário sem casas decimais desnecessárias
- [ ] Negrito para ênfase, não MAIÚSCULAS

### Estrutura de ficheiros
- [ ] Apenas ficheiros que o agente precisa para o trabalho
- [ ] Sem README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
- [ ] References com índice se >100 linhas
- [ ] Scripts testados se incluídos

### Padrões Descomplicar
- [ ] MCPs relevantes referenciados (se aplicável)
- [ ] Assinatura Descomplicar® no código produzido (se aplicável)
- [ ] Graus de liberdade calibrados ao risco da operação

### Validação técnica (Regra #49)
- [ ] Código auditado: segurança, erros, boas práticas, performance
- [ ] Score 10/10 antes de entregar