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:

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)

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

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

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

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:

{"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.

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