Hook tab pendencias reminder

Hook: tab-pendencias-reminder

Esta página explica o hook tab_pendencias_reminder.py de forma didática. Se algum termo for novo, consulte o Glossário.

O que é um hook

Um hook (gancho automático) é um pequeno programa que dispara sozinho em um momento específico, sem você pedir. O bigtech traz 6 hooks; este é um deles.

O que o tab-pendencias-reminder faz

O tab-pendencias-reminder cuida da tabela de tarefas do projeto (o arquivo TODO.md). Ele faz duas coisas, sempre como lembrete leve:

1. Quando a tabela ainda não existe num projeto que já teve o porte medido, ele sugere criá-la rodando a skill /tab_pendencias.
2. Quando a tabela já existe, ele vigia se ela está defasada (esquecida, sem ser atualizada) e avisa para você dar uma revisada.

O nome significa "lembrete de tabela de pendências". "Tabela de pendências" é a lista do que falta fazer no projeto, ordenada para evitar retrabalho (veja a Skill: /tab_pendencias). "Defasagem" aqui quer dizer: a tabela ficou para trás em relação ao trabalho que de fato aconteceu no projeto.

Os três gatilhos

O hook tem três situações em que pode aparecer. Elas se dividem entre dois momentos: o início da sessão (SessionStart) e cada mensagem que você envia (UserPromptSubmit).

1. Criar a tabela (no início da sessão)

Este é o comportamento histórico. No SessionStart, o lembrete aparece quando as duas condições são verdadeiras ao mesmo tempo:

1. O projeto já foi classificado pela /bigtech: existe o arquivo marcador .bigtech-porte na raiz.
2. O projeto ainda não tem o arquivo TODO.md na raiz.

Se faltar o marcador .bigtech-porte, este hook fica calado: quem lembra, nesse caso, é o bigtech-porte-reminder. Assim que o TODO.md é criado, este lembrete de criação para de aparecer.

2. Defasagem por git (no início da sessão)

Quando o TODO.md já existe, no SessionStart o hook mede o quanto a tabela está atrasada. Para isso ele consulta o histórico do git (a ferramenta que registra a história das mudanças do projeto) e calcula duas coisas:

• Quantos commits foram feitos desde a última vez que o TODO.md foi alterado. Um "commit" é um ponto salvo na história do projeto.
• Quantos dias se passaram desde esse último toque na tabela.

Se esses números passarem dos limiares configurados, o hook avisa que a tabela pode estar defasada e sugere revisá-la. A ideia é simples: se muita coisa mudou no código mas a tabela de tarefas ficou parada, ela provavelmente não reflete mais a realidade.

3. Sessão longa (a cada mensagem)

Quando o TODO.md existe e você está há várias horas na mesma sessão, o hook dá um nudge (cutucão gentil) único pedindo que você revise e reordene a tabela. Esse gatilho roda no UserPromptSubmit, ou seja, é avaliado quando você envia mensagens. Por isso o hook agora dispara em dois eventos (SessionStart e UserPromptSubmit), e não só no início.

Como ajustar os limiares: .tab-staleness.json

Os limiares têm valores embutidos que funcionam bem na maioria dos casos, então você não precisa configurar nada. Se quiser personalizar, crie um arquivo .tab-staleness.json na raiz do projeto com qualquer um destes campos:

• commits: quantos commits sem tocar no TODO.md já contam como defasagem.
• dias: quantos dias sem tocar no TODO.md já contam como defasagem.
• modo: "e" exige os dois limiares juntos (commits e dias) para avisar; "ou" basta um dos dois.
• horas_sessao: depois de quantas horas de sessão o nudge de revisão aparece.
• off: se for true, desliga os gatilhos de defasagem (2) e de sessão longa (3). O lembrete de criar a tabela (1) continua funcionando.

Quem cria ou reordena a tabela

O hook apenas avisa; ele nunca cria nem reordena a tabela sozinho. Quem inicia a skill /tab_pendencias é a thread principal (a conversa com você), porque os agentes especialistas não têm a ferramenta que dispara skills. Quando você roda a /tab_pendencias, a skill gera ou reorganiza o TODO.md com as tarefas na ordem recomendada (por dependência e por valor, agrupadas em ondas).

Ele lê o git em modo somente-leitura

Para medir a defasagem, o hook executa comandos de consulta do git (como git rev-list e git log), com argumentos fixos e sem passar por um shell. Ele só lê o histórico: não grava nada no repositório, não acessa a rede e não altera arquivos. É um comportamento benigno, detalhado no SECURITY.md do projeto.

Ele nunca trava o seu trabalho

Este hook foi feito para nunca interromper a sessão. Ele é apenas um lembrete: sempre termina sem erro e nunca bloqueia o turno. Se algo der errado (não há git, o projeto não é um repositório, a saída do git veio diferente do esperado), ele simplesmente não mostra nada. Esse comportamento se chama fail-open: na dúvida, deixa passar.

Relação com os outros hooks

• O bigtech-porte-reminder é o passo anterior: lembra de medir o porte quando ele ainda não foi classificado. Este aqui assume a vez logo depois, quando o porte já existe.
• O bigtech-session-init também roda no início da sessão, para carregar os manuais e avisar de compatibilidade.
• O bigtech-reinforce faz o reforço do modo a cada mensagem; este aqui, no UserPromptSubmit, faz só o nudge de sessão longa.

---

Veja também a Skill: /tab_pendencias e o Uso no dia a dia. Voltar para a Home.