Files

T

Claude Code AI 49502c59da fix(gestao): corrige YAML frontmatter invalido em qw/worklog, remove ijfw_memory_recall morto, recupera report-5w2h perdido, bump 1.6.1

2026-07-04 14:21:39 +01:00

15 KiB

Raw Blame History

name, description

name	description
worklog	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 <branch>`
      - 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 <path>` 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:

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)

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

<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

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®

15 KiB Raw Blame History