402 lines
15 KiB
Markdown
402 lines
15 KiB
Markdown
---
|
|
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 <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:**
|
|
|
|
```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
|
|
<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
|
|
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
|
|
<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®*
|