claude-plugins/gestao/skills/worklog/SKILL.md

---
name: worklog
description: Registo de trabalho e reflexão unificado. Analisa sessão, regista trabalho, identifica padrões, sugere acções. /reflect é alias (mesmo resultado). Variantes: deep (análise profunda), week (revisão semanal). Usar quando "worklog", "reflect", "reflexão", "registar trabalho", "log", ao parar timer.
---

# /worklog v4.1 - Registo de Trabalho + Reflexão

**⚠️ EXECUÇÃO INLINE OBRIGATÓRIA — NUNCA FORK**

Quando `/worklog` ou `/reflect` é invocado, o agente principal executa o protocolo **directamente, in-situ, no thread principal**. Proibido:
- Chamar `Skill tool` para `worklog`/`reflect` (fork perde contexto conversacional — histórico de mensagens, Edit/Write calls, MCP tool calls, decisões já tomadas)
- Chamar `Agent tool` / Task subagente para executar o worklog (mesma razão)

O histórico da conversa actual é a **fonte primária** do worklog. Só o agente principal o tem. Qualquer fork devolve "nothing to log" e falha silenciosamente o registo — anti-padrão verificado empiricamente em 2026-04-23.

Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda memória.

**`/reflect` = alias de `/worklog`** (mesmo resultado).

---

## Comandos

| Comando | Função |
|---------|--------|
| `/worklog` | Registo + reflexão da sessão |
| `/reflect` | Alias de `/worklog` |
| `/worklog view` | Ver últimos registos |
| `/reflect deep` | Análise profunda com histórico |
| `/reflect week` | Revisão semanal (segundas via /today) |

---

## Storage

| Tipo | Discussão | ID |
|------|-----------|-----|
| **Logs + Reflexões** | Logs | 31 |
| **Reflexões Profundas** | Reflexões | 32 |
| **Acções** | Acções de Melhoria | 33 |

**Projecto:** #65 (DES Stack Workflow) | **Staff:** 25 (AikTop)

---

## Protocolo Principal (/worklog e /reflect)

```
1. Obter hora via mcp__mcp-time__current_time
2. Verificar timer activo em ~/.claude-work/active-timer.json
3. ANALISAR sessão — FONTE PRIMÁRIA é o histórico conversacional actual do agente:
   A) **Contexto conversa (OBRIGATÓRIO — FONTE PRIMÁRIA):**
      O agente que executa esta skill tem, no seu próprio histórico, toda a informação que precisa.
      Extrair directamente:
      - Ficheiros modificados (procurar Edit/Write/MultiEdit nos tool_use da sessão)
      - MCPs usados (procurar mcp__*__* tool calls)
      - Erros encontrados e soluções aplicadas
      - Padrões detectados, decisões arquitecturais
      - Pedidos sucessivos do utilizador (sequência de mensagens user)
      - Commits feitos (procurar `git commit` em tool_use)
      - Subagentes dispatched (Agent tool calls)

   B) **Contexto externo (COMPLEMENTAR — SEMPRE recolher):**
      - git diff --stat (últimas 3h): ficheiros alterados
      - git log --oneline --since="3 hours ago": commits recentes
      - SQLite Observabilidade (se disponível): `~/.claude-work/sessions.db` tabela sessions com project_slug+started_at+tool_calls da sessão actual
      - find 00-Inbox/ -name "worklog-$(date +%Y-%m-%d)*" -newer
      - Ficheiros modificados nas últimas 3h no working directory
      - Tarefas Desk com comentários criados hoje (mcp__desk-crm-v3__get_task_comments filter staff_id=1 or 25)

   C) **Activity log do hook (FALLBACK — cross-session apenas):**
      Usar só quando A) está genuinamente vazio (ex: /worklog invocado manualmente sem contexto activo).
      - ls -lat ~/.claude-work/sessions/*.activity.log | head -5
      - Escolher activity.log MAIOR modificado nas últimas 2h (>5KB)
      - Ler o .json correspondente para metadata

   REGRA: A) preenche o corpo do worklog. B) adiciona detalhes. C) só se A) vazio.
   REGRA: Se A), B) e C) todos vazios após verificação rigorosa → NÃO gerar e reportar "nada novo para registar".
3b. VERIFICAR alinhamento com spec (se aplicavel):
   - Detectar ficheiros modificados na sessao
   - Procurar SPEC.md no directorio pai (ate 3 niveis)
   - SE spec approved/in_progress: comparar ficheiros vs scope items
   - SE ficheiro nao mapeia para scope: incluir SCOPE ALERT no worklog
   - SE sem SPEC.md: ignorar silenciosamente
4. VERIFICAR se há algo novo a documentar
   - Se conversa vazia → recolher contexto externo (passo 3B)
   - Se contexto externo tambem vazio → NÃO gerar
   - NUNCA desistir sem verificar fontes externas primeiro
5. Gerar comentário HTML (ver formato abaixo)
6. mcp__desk-crm-v3__add_discussion_comment({
     discussion_id: 31,
     content: html,
     staff_id: 25
   })
7. SE acções sugeridas:
   mcp__desk-crm-v3__add_discussion_comment({
     discussion_id: 33,
     content: accoes_html,
     staff_id: 25
   })
7b. TRIGGER improvement-evaluator no desktop (localhost):
   Bash: curl -s -X POST http://localhost:8095/trigger
   (falha silenciosa OK — o systemd timer apanha em 30min)
8. SE insight valioso → save_memory Supabase COM TAGS (ver criterios abaixo)
8b. GIT CHECKPOINT (automático se em projecto git):
   a. Verificar se existe `.desk-project` no directório actual (ou até 3 níveis acima)
   b. Se sim: verificar se é repositório git (`git rev-parse --git-dir`)
   c. Se sim: verificar se há alterações pendentes (`git status --porcelain`)
   d. Se há alterações:
      - Gerar entrada CHANGELOG a partir da secção "Trabalho Realizado":
        `- YYYY-MM-DD [tarefa #ID] Descrição concisa do trabalho feito`
        Inserir em `## [Unreleased]` do CHANGELOG.md
      - `git add -A`
      - `git commit -m "worklog: [tarefa #ID] descrição da sessão"`
      - `git push origin <branch>`
      - Registar resultado no output final
   e. Se sem alterações: omitir silenciosamente
9. Confirmar
```

**Output:**

```markdown
Worklog registado!

Tarefa: #1446 - Documentação Skills
Duração: 2h 15m
Discussão: #31 (Logs)
Acções: 2 sugeridas (#33)
Memória: Guardada / N/A
Git: commit abc1234 → push OK
```

---

## Formato Comentário HTML (Discussão #31)

```html
<h4>YYYY-MM-DD HH:MM - Título da Sessão</h4>

<p><strong>Projecto:</strong> Nome</p>
<p><strong>Tarefa:</strong> #ID - Nome</p>
<p><strong>Duração:</strong> ~XXh YYm</p>
<p><strong>Resultado:</strong> Concluído | Parcial | Bloqueado</p>

<h4>Trabalho Realizado</h4>
<ul>
  <li>Acção 1</li>
  <li>Acção 2</li>
</ul>

<h4>Ficheiros Modificados</h4>
<ul>
  <li><code>path/file.ext</code> - descrição</li>
</ul>

<h4>Problemas / Soluções</h4>
<ul>
  <li><strong>Problema:</strong> Descrição
      <br><strong>Solução:</strong> Como foi resolvido</li>
</ul>

<h4>Alertas de Scope</h4>
<ul>
  <li><strong>SCOPE ALERT:</strong> <code>path</code> nao mapeado no SPEC</li>
</ul>

<h4>Padrões Detectados</h4>
<ul>
  <li>Padrão identificado e impacto</li>
</ul>

<h4>Acções Sugeridas</h4>
<p><em>Detalhes na discussão #33</em></p>
<ul>
  <li>[Tipo] Descrição breve</li>
</ul>

<h4>Próximos Passos</h4>
<ol>
  <li>Tarefa pendente 1</li>
</ol>
```

---

## Formato Acções (Discussão #33)

Cada acção num comentário separado:

```html
<p>- [ ] [Tipo] Descrição da acção</p>
<p><strong>Origem:</strong> Worklog YYYY-MM-DD HH:MM</p>
<p><strong>Prioridade:</strong> P1/P2/P3</p>
<p><strong>Contexto:</strong> Breve explicação</p>
```

**Tipos:** `[CLAUDE.md]`, `[Skill]`, `[MCP]`, `[Workflow]`, `[Bug]`, `[Feature]`

---

## /worklog view

```
1. mcp__desk-crm-v3__get_project_discussions({ project_id: 65 })
2. Filtrar discussão #31
3. Mostrar últimos 5 comentários
```

---

## /reflect deep (Análise Profunda)

Análise mais detalhada que o worklog normal. Publica em discussão **#32** (Reflexões).

```
1. Ler comentários recentes de #31 (worklogs) e #32 (reflexões)
2. Analisar padrões repetidos
3. Comparar eficiência com sessões anteriores
4. Verificar TaskForces utilizadas (ver Integração TaskForce)
5. Gerar comentário detalhado em #32
6. Acções em #33
7. Memória Supabase
```

---

## /reflect week (Revisão Semanal)

Chamado automaticamente pelo `/today` às segundas-feiras. Publica em **#32**.

```
1. Ler comentários de #31 e #32 da semana
2. Agregar padrões e métricas
3. Gerar resumo semanal
4. Identificar melhorias prioritárias
```

**Formato:**

```html
<h4>Semana YYYY-WNN - Revisão</h4>

<h4>Métricas</h4>
<table>
  <tr><td>Sessões registadas</td><td>N</td></tr>
  <tr><td>Reflexões geradas</td><td>M</td></tr>
  <tr><td>Padrões detectados</td><td>P</td></tr>
</table>

<h4>Padrões Frequentes</h4>
<ol><li>Padrão A - Nx detectado</li></ol>

<h4>Melhorias Prioritárias</h4>
<ul>
  <li>[ ] [P1] Descrição</li>
  <li>[ ] [P2] Descrição</li>
</ul>

<h4>Plano Esta Semana</h4>
<ul>
  <li>Implementar: X</li>
  <li>Monitorar: Y</li>
</ul>
```

---

## Integração /time

Quando `/time stop` é executado:

```
1. Timer parado
2. Mostrar resumo (tarefa, duração)
3. Perguntar: "Criar worklog? [Sim/Não]"
4. Se sim → Gerar worklog com contexto do timer
```

---

## Auto-Save Memória (Passo 8)

**Destino:** `mcp__memory-supabase__save_memory` — para conhecimento pesquisavel semanticamente.
**NAO usar para:** regras estaveis de sessao (→ CC memory ficheiro .md) ou factos rapidos (→ QR-*.md).

### Criterios: guardar ou nao

| Tipo | Exemplo | Guardar? | Tag tipo |
|------|---------|----------|----------|
| Solucao tecnica nova | Fix para erro MCP | Sim | `solucao-tecnica` |
| Configuracao sistema | Novo MCP configurado | Sim | `configuracao` |
| Workaround descoberto | Bypass para bug | Sim | `workaround` |
| Padrao novo | "X funciona melhor que Y" | Sim | `padrao` |
| Decisao arquitectural | Escolha de abordagem | Sim | `decisao` |
| Incidente resolvido | Crash + root cause | Sim | `incidente` |
| Pipeline criado/alterado | Novo workflow n8n | Sim | `pipeline` |
| Licao aprendida | Abordagem A falhou, B funcionou | Sim | `lesson-learned` |
| Trabalho rotineiro | Updates, limpeza | Nao | — |
| Feedback do user | "nao faz X" | Nao (→ CC memory) | — |
| ID/path/comando novo | Nova porta, novo ID | Nao (→ QR-*.md) | — |

### Taxonomia de tags obrigatoria

```
tags: [tipo, dominio, projecto?, data-yyyy-mm]
```

**tipo** (obrigatorio): `solucao-tecnica` | `decisao` | `padrao` | `incidente` | `configuracao` | `pipeline` | `lesson-learned` | `workaround`

**dominio** (obrigatorio): `infra` | `wordpress` | `crm` | `paperclip` | `inteligencia` | `seo` | `dev` | `hub` | `mcp` | `podcast` | `marketing`

**projecto** (opcional): `fluxo-seo` | `pleno` | `whatsms` | `inteligencia` | `rag-system` | etc

**data** (obrigatorio): formato `yyyy-mm` (ex: `2026-04`)

**Exemplo:**
```javascript
mcp__memory-supabase__save_memory({
  content: "Fix MCP memory-supabase: stats retornava 100 em vez de 11.936. Causa: chamava getAllMemories (cap 100) em vez de getMemoryStatistics(). Solução: chamar RPC directamente.",
  tags: ["solucao-tecnica", "mcp", "rag-system", "2026-04"]
})
```

---

## Checklist de Reflexão

Perguntas ao analisar sessão:

- O sistema respondeu bem aos pedidos?
- Houve confusão ou mal-entendidos?
- Alguma tarefa repetitiva deveria ser skill?
- Faltou informação que deveria estar em memória?
- Alguma regra CLAUDE.md foi violada?
- Os MCPs funcionaram correctamente?
- **Context health:** CLAUDE.md global <200 linhas? MEMORY.md <80 linhas? (Ref: DEV-CTX-001)

---

## Auto-Alerts Data-Driven

| Alerta | Threshold | Acção |
|--------|-----------|-------|
| Degradação performance | >15% vs baseline (7d) | Investigar causa |
| Error rate alto | >10% (30d) | Analisar erros |
| KB offline | 3 timeouts | Verificar MCP |

**Formato alerta:** Inclui componente, tipo, threshold, valor actual, investigação e acções sugeridas.

---

## Integração TaskForce (para /reflect deep)

```
1. LER ~/.claude/sdks/_registry.json
2. COMPARAR com skills/agents usados na sessão
3. SE match: adicionar secção "SDKs Utilizados" com tempo e baseline
```

---

## Auto-Trigger

| Trigger | Acção |
|---------|-------|
| >10 tool calls | Gerar worklog background |
| Parar timer | Oferecer criar worklog |
| Mudança de projecto | Fechar sessão anterior |
| Mesmo erro 2+ vezes | Analisar causa |
| Segunda-feira via /today | Revisão semanal |

---

## Anti-Patterns

- **NUNCA** criar worklog sem dados de sessão NEM de contexto externo
- **NUNCA** declarar "sessão vazia" sem verificar git diff, logs e ficheiros recentes
- **NUNCA** usar Markdown em comentários (usar HTML)
- **NUNCA** guardar memória para trabalho rotineiro
- **NUNCA** duplicar reflexão e worklog (são o mesmo)
- **NUNCA** ignorar worklogs manuais em 00-Inbox — se existem, usá-los como fonte

---

## Changelog

### v4.6.0 (2026-04-20)
- Fix critico cross-session: /worklog invocado como slash command abre sessão nova — agora escolhe o activity.log MAIOR das últimas 2h em vez de session_id actual
- Passo 3C expandido: find em Hub/mcp-servers/systemd/plugins/.claude-work (3h) + check comentários Desk do dia
- Anti-pattern reforçado: activity.log <5KB = sessão wrapper, não real — ignorar

### v4.5.0 (2026-04-13)
- Passo 8 expandido: criterios claros para guardar em Supabase vs CC memory vs QR
- Taxonomia de tags obrigatoria: [tipo, dominio, projecto?, data-yyyy-mm]
- 8 tipos de tag, 11 dominios, exemplo concreto de save_memory

### v4.4.0 (2026-04-13)
- Git checkpoint integrado como passo 8b: detecta .desk-project + git, gera entrada CHANGELOG rica a partir do "Trabalho Realizado", commit + push automático no fim de cada worklog

### v4.3.0 (2026-04-12)
- Fix critico: sessão vazia não aborta sem verificar contexto externo
- Passo 3B: recolha obrigatoria de git diff, logs, ficheiros recentes e worklogs manuais
- Regra: se conversa vazia mas contexto externo tem dados, usar contexto externo
- Anti-pattern actualizado: nunca declarar "sessão vazia" sem verificar fontes externas

### v4.2.1 (2026-04-20)
- Trigger improvement-evaluator migrado de SSH dev→curl localhost (CT 102 abatido, serviço no desktop via systemd)

### v4.2.0 (2026-03-12)
- Integração improvement-evaluator: passo 7b trigger automático ao dev (POST :8095/trigger)
- Acções publicadas em #33 são avaliadas imediatamente pelo agente cron no dev

### v4.0.0 (2026-02-06)
- Fusão de /worklog e /reflect numa skill unificada
- /reflect torna-se alias de /worklog
- Discussão #31 recebe tudo (worklog + reflexão)
- Discussão #32 reservada para /reflect deep e /reflect week
- Checklist de reflexão integrado
- Auto-alerts data-driven integrados
- Integração TaskForce mantida para /reflect deep

### v3.0.0 (2026-02-05)
- Integração completa com /time
- Auto-trigger ao parar timer
- Formato HTML alinhado com Regra #27



---

## Self-Healing

Antes de executar, ler `~/.claude-work/healing/worklog.jsonl` (se existir). Cada linha é um padrão de erro conhecido:

```json
{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"}
```

Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido.

---

*Skill v4.3.0 | 2026-04-12 | Descomplicar(R)*

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"2026-04-12","issue":"Sessão declarada vazia quando havia trabalho real (15 episódios podcast produzidos). Skill abortou sem verificar fontes externas.","fix":"Sempre executar passo 3B (git diff, logs, ficheiros recentes, worklogs manuais) antes de declarar sessão vazia. Se contexto externo tem dados, usar como fonte principal.","source":"user"}
```

*Adicionar nova linha após cada erro corrigido.*

---

*Skill v4.5.0 | 2026-04-13 | Descomplicar®*