fix(worklog): v4.1 — proíbe fork via Skill/Agent tool (perde contexto)

Skills /worklog e /reflect dependem do histórico conversacional do agente principal. Invocá-las via Skill tool ou Agent tool cria subagente sem contexto e reporta 'nothing to log'. Banner obrigatório no topo, fonte A (conversa) reforçada como primária, fonte C (activity log) rebaixada para fallback. Incidente 2026-04-23: após 28h+ trabalho Observabilidade, /worklog via Skill tool retornou vazio.
2026-04-23 03:35:40 +01:00
parent b6690a75fd
commit d3f9c950cd
1 changed files with 130 additions and 28 deletions
@@ -1,10 +1,17 @@
 ---
 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.
-context: fork
 ---

-# /worklog v4.0 - Registo de Trabalho + Reflexão
+# /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.

@@ -41,12 +48,34 @@ Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda mem
 ```
 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)
+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)
@@ -54,7 +83,9 @@ Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda mem
   - 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
+   - 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,
@@ -67,13 +98,23 @@ Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda mem
     content: accoes_html,
     staff_id: 25
   })
-7b. TRIGGER improvement-evaluator no dev:
-   mcp__ssh-unified__ssh_execute({
-     server: "dev",
-     command: "curl -s -X POST http://localhost:8095/trigger"
-   })
-   (falha silenciosa OK — o cron apanha em 30min)
-8. SE insight valioso → save_memory Supabase
+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
 ```

@@ -87,6 +128,7 @@ Duração: 2h 15m
 Discussão: #31 (Logs)
 Acções: 2 sugeridas (#33)
 Memória: Guardada / N/A
+Git: commit abc1234 → push OK
 ```

 ---
@@ -237,16 +279,48 @@ Quando `/time stop` é executado:

 ---

-## Auto-Save Memória
+## Auto-Save Memória (Passo 8)

-| 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 |
+**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"]
+})
+```

 ---

@@ -300,15 +374,39 @@ Perguntas ao analisar sessão:

 ## Anti-Patterns

- **NUNCA** criar worklog sem dados de sessão
+- **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
@@ -343,7 +441,7 @@ Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivam

 ---

-*Skill v4.2.0 | 2026-03-12 | Descomplicar(R)*
+*Skill v4.3.0 | 2026-04-12 | Descomplicar(R)*

 ---

@@ -352,7 +450,11 @@ Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivam
 Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

 ```jsonl
-{"date":"","issue":"","fix":"","source":"user|auto"}
+{"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®*