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

YYYY-MM-DD HH:MM - Título da Sessão

Projecto: Nome

Tarefa: #ID - Nome

Duração: ~XXh YYm

Resultado: Concluído | Parcial | Bloqueado

Trabalho Realizado

Ficheiros Modificados

Problemas / Soluções

Alertas de Scope

Padrões Detectados

Acções Sugeridas

Detalhes na discussão #33

Próximos Passos

  1. Tarefa pendente 1
``` --- ## Formato Acções (Discussão #33) Cada acção num comentário separado: ```html

- [ ] [Tipo] Descrição da acção

Origem: Worklog YYYY-MM-DD HH:MM

Prioridade: P1/P2/P3

Contexto: Breve explicação

``` **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

Semana YYYY-WNN - Revisão

Métricas

Sessões registadasN
Reflexões geradasM
Padrões detectadosP

Padrões Frequentes

  1. Padrão A - Nx detectado

Melhorias Prioritárias

Plano Esta Semana

``` --- ## 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®*