From d3f9c950cd06a80988b0bd1f957bcae8ca27cdc7 Mon Sep 17 00:00:00 2001 From: Emanuel Almeida Date: Thu, 23 Apr 2026 03:35:40 +0100 Subject: [PATCH] =?UTF-8?q?fix(worklog):=20v4.1=20=E2=80=94=20pro=C3=ADbe?= =?UTF-8?q?=20fork=20via=20Skill/Agent=20tool=20(perde=20contexto)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- gestao/skills/worklog/SKILL.md | 158 +++++++++++++++++++++++++++------ 1 file changed, 130 insertions(+), 28 deletions(-) diff --git a/gestao/skills/worklog/SKILL.md b/gestao/skills/worklog/SKILL.md index 0aa13f0..6528a6d 100644 --- a/gestao/skills/worklog/SKILL.md +++ b/gestao/skills/worklog/SKILL.md @@ -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 ` + - 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®*