--- name: worklog description: "Registo de trabalho e reflexão unificado. Analisa sessão, regista trabalho, identifica padrões, sugere acções, higieniza documentação Hub. /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.8.0 - Registo de Trabalho + Reflexão + Higienizaçã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. **`/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: - Ficheiros modificados (Edit/Write calls) - MCPs usados - Erros e soluções - Padrões detectados - Eficiência (tool calls vs resultado) 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 sessão vazia/sem dados → NÃO gerar 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. SUGESTÕES DE MELHORIA — avaliação autónoma (NÃO chamar nada): As sugestões ficam registadas no passo 7 (Discussão #33). O Improvement Evaluator v2 (cronjob Hermes no desktop, job d398b5e2c3be) lê os registos do worklog/#33 autonomamente e leva-os para a sua BD; corre diariamente e gera ticket "Sugestões de Melhoria — Semana X" às segundas. O /worklog NÃO dispara nem chama o evaluator — apenas regista. (v1 HTTP :8095 http-trigger.py descontinuada/arquivada em 99-Arquivo/improvement-evaluator-v1-legado/. Servidor "dev"/CT 102 abatido em 20-04-2026 — Regra #48; qualquer chamada ssh_execute(server:"dev") falha sempre, não usar.) 8. SE insight valioso → save_memory Supabase 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 (não mencionar) 9. HIGIENIZAÇÃO (obrigatório SE algum .md dentro do Hub foi criado/editado nesta sessão — PROC-Higienizacao-Documental.md, XDP-HIG-001): a. CRIAR OKF: para cada .md novo que representa sistema/aplicação/processo real (não nota solta, não template) — verificar se já existe ficha de entidade. Se não existe: criar 5W2H-PDCA agora, não adiar. `bash 04-Stack/scripts/okf-detect-new.sh --hub --json /tmp/wl-detect.json` para listar candidatos; `bash 04-Stack/scripts/okf-suggest-entity.sh ` para gerar proposta por ficheiro. b. ACTUALIZAR REFERÊNCIAS: se alguma métrica/nome/link mudou nesta sessão, grep pelo valor antigo nos documentos "vivos" (mapas de ecossistema, STK-Estado-Actual, fichas OKF relacionadas) e propagar a correcção. Documentos históricos datados (changelogs antigos, snapshots rotulados "auditado em DD-MM") NÃO se reescrevem. c. ELIMINAR FICHEIROS DESNECESSÁRIOS: procurar `.bak`/`.tmp`/rascunhos/relatórios `VALIDACAO-FASE-F-*.md` avulsos criados nesta sessão e remover antes do fecho. d. ORGANIZAR E INDEXAR: directório novo criado nesta sessão tem `index.md`? Está referenciado no MOC/índice do directório pai? Se não, corrigir agora. e. Se algum dos 4 tópicos foi genuinamente ignorado (ex: nenhum .md tocado), omitir silenciosamente esta secção do output. Se foi aplicável e ficou por fazer, reportar como bloqueio explícito — nunca como "nota para depois". 10. 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 Higienização: N/A (sem alterações no Hub) | OK (4/4 tópicos) | 2 pendências reportadas como bloqueio ``` --- ## 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 5. FAXINA DE REPO (semanal — âmbito repo inteiro, complementa o Passo 9 diário que só vê a sessão): a. LIXO → QUARENTENA (nunca rm directo — eliminação é T3): - detectar por padrão mecânico: *.bak, *.tmp, *~, .xdp-*, VALIDACAO-FASE-F-*.md com >7 dias, duplicados exactos por checksum (md5sum) - mover para 99-Arquivo/quarentena/YYYY-WW/ preservando path relativo - listar no relatório semanal (#32) para aprovação do Emanuel - purga: só de quarentenas com >30 dias E semana aprovada — nunca na mesma semana b. ÍNDICES vs REALIDADE: contagens/listas declaradas em index.md e MOCs vs `find` real (check V-INDICE/N4 do APROFUNDAMENTO 01) — divergência → corrigir o índice, reportar no resumo c. OKF SEMANAL: `bash 04-Stack/scripts/okf-detect-new.sh --hub` sobre a semana inteira (apanha o que os Passos 9a diários deixaram escapar) d. Output ganha secção "Faxina": N em quarentena / M índices corrigidos / K fichas OKF criadas ``` **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 | Tipo | Exemplo | Guardar? | |------|---------|----------| | Solução técnica nova | Fix para erro MCP | Sim | | Configuração sistema | Novo MCP configurado | Sim | | Workaround descoberto | Bypass para bug | Sim | | Padrão novo | "X funciona melhor que Y" | Sim | | Decisão arquitectural | Escolha de abordagem | Sim | | Trabalho rotineiro | Updates, limpeza | Não | --- ## 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 - **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** fazer fork (Skill tool/Agent tool) para executar /worklog — perde o contexto conversacional que é a fonte primária. Anti-padrão verificado 2026-04-23. - **NUNCA** omitir o Passo 9 (Higienização) quando a sessão tocou ficheiros do Hub — nem reportar "arrumado" sem correr os 4 tópicos. - **NUNCA** chamar `ssh_execute(server: "dev")` ou qualquer referência ao servidor `dev`/CT 102 — abatido em 20-04-2026 (Regra #48), o alias já não existe em `~/.ssh/config`. - **NUNCA** `rm` directo na faxina semanal — eliminação é T3 (irreversível): quarentena → aprovação → purga 30d. Um falso positivo com rm destrói trabalho; com quarentena custa um `mv`. --- ## Changelog ### v4.8.0 (2026-07-03) - `/reflect week` ganha passo 5 (Faxina de Repo): quarentena de lixo por padrão mecânico (*.bak, *.tmp, *~, .xdp-*, VALIDACAO-* >7d, duplicados por checksum) em `99-Arquivo/quarentena/YYYY-WW/` com aprovação humana e purga a 30d; revisão índices vs disco (check V-INDICE/N4); okf-detect-new semanal. Complementa o Passo 9 diário (âmbito sessão) com âmbito repo. Racional: eliminação é T3 na matriz de tiers (SPEC Pipeline QT); diário=delta, semanal=estado. ### v4.7.1 (2026-07-02) - **Bug corrigido:** passo 7b chamava `mcp__ssh-unified__ssh_execute({ server: "dev", ... })` para disparar o improvement-evaluator — servidor `dev`/CT 102 foi abatido em 20-04-2026 (Regra #48), chamada falhava sempre (dead code). Substituído por texto informativo: o evaluator é 100% autónomo (cronjob Hermes no desktop), `/worklog` nunca dispara nada. - Sincronizado conteúdo entre skill instalada (1.3.0), skill em cache (1.4.0) e fonte marketplace (que estava truncada a 107 linhas) — as três eram divergentes. ### v4.7.0 (2026-07-02) - Passo 9 (Higienização) novo: obrigatório sempre que a sessão tocou .md do Hub — 4 tópicos (criar OKF, actualizar referências, eliminar ficheiros desnecessários, organizar e indexar). Ver PROC-Higienizacao-Documental.md, XDP-HIG-001, regra CARL GLOBAL#19. - Frontmatter corrigido: removido `context: fork` (bug — contradizia a regra "nunca fork" já documentada; causava perda de contexto conversacional em produção). Aviso inline reforçado no topo do ficheiro. - Output final ganha linha "Higienização: ..." ### v4.3.0 (2026-04-13) - Git checkpoint integrado como passo 8b: detecta .desk-project + git, gera entrada CHANGELOG rica, commit + push automático no fim de cada worklog ### v4.2.0 (2026-03-12) - Integração improvement-evaluator: passo 7b trigger automático ao dev (POST :8095/trigger) — **descontinuado na v4.7.1** (ver acima) - 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 --- *Skill v4.8.0 | 2026-07-03 | Descomplicar®*