Avishai-Tsabari/mercury-skills

Tracker — acompanhando trabalho que se move

Quando esta é a habilidade certa

Pergunta-chave: "Qual é o status de…?" ou "Quem é o responsável por isso?"

Um tracker = itens que se movem entre estados, com responsável e cronograma, e com histórico que vale a pena preservar.

O teste de roteamento

Você precisa de pelo menos dois destes para justificar um tracker:

• Um status que muda ao longo do tempo (não um atributo — movimento)
• Um responsável humano
• Uma data de vencimento
• Uma hierarquia: grupo → subgrupo → item

Menos de dois? → registry. ⚠️ O padrão é sempre registry.

Como é construído

Um mecanismo, muitos esquemas.

<tracker-dir>/
  schema.json    statuses, prioridades, rótulos de hierarquia, campos extras
  tracker.db     SQLite: itens + grupos + item_history

Mecanismo: engine/tracker.py (ao lado deste SKILL.md) · Python 3.9+ · zero dependências (sqlite3 nativo).

Hierarquia: group → subgroup → item. Os rótulos mudam por domínio — para tarefas é projeto → módulo → tarefa, para bugs é produto → componente → bug, para faturas é cliente → assinatura → fatura.

Trabalhando com o usuário

1. Execute o teste de roteamento. Uma lista plana → registry.
2. Proponha um esquema: quais status, o que conta como "fechado", quais prioridades, qual a hierarquia, quais campos extras. Apresente e peça aprovação.
3. Verifique se há um preset em presets/.
4. Crie com init, adicione grupos, depois registre o tracker no índice registries.json do workspace.
5. Explique que as atualizações podem ser relatadas em linguagem natural — o agente as traduz em comandos.

Comandos

Os caminhos são relativos à raiz do workspace. Ajuste SKILL_DIR para onde esta habilidade está instalada (ex.: .pi/skills/tracker).

T=<SKILL_DIR>/engine/tracker.py
D=trackers/bugs

python3 $T --dir $D init --preset bugs
python3 $T --dir $D group add webapp --name "Web App"
python3 $T --dir $D group add checkout --name "Checkout" --parent webapp
python3 $T --dir $D add "Reserva duplicada no calendário" --group webapp --subgroup checkout \
        --assignee dana --priority sev2 --client acme --due 2026-08-05
python3 $T --dir $D update 3 --status em-andamento --notes "reproduzido"
python3 $T --dir $D list --assignee dana --group-by status
python3 $T --dir $D list --status bloqueado
python3 $T --dir $D show 3
python3 $T --dir $D history 3
python3 $T --dir $D report          # resumo: por status, por responsável, atrasados, bloqueados
python3 $T --dir $D delete 3 --yes  # ⚠️ exclusão permanente

list sem filtro oculta automaticamente itens fechados. --all mostra tudo.

Presets disponíveis

tasks tarefas · bugs bugs e problemas de cliente · invoices faturas e cobrança · features pipeline de funcionalidades

Ordem de resolução de presets

init --preset <nome> resolve <nome>.json nesta ordem — o primeiro encontrado vence:

1. <workspace>/trackers/presets/<nome>.json — presets locais do espaço, relativos ao diretório de trabalho de onde o mecanismo é executado
2. <SKILL_DIR>/presets/<nome>.json — os embutidos listados acima

Um preset local com o mesmo nome de um embutido o substitui. Um preset ausente lista todos os nomes disponíveis de ambas as localizações, identificados como [espaço] / [embutido].

Criando um preset local: coloque um esquema JSON (mesmo formato de schema.json, veja os embutidos como exemplos) em trackers/presets/. O diretório só é lido em um --preset <nome> explícito — outros arquivos ali são ignorados.

Regras de ferro

• 📊 O tracker é a fonte da verdade — nunca mantenha status na memória do agente. Sempre consulte.
• ⛔ Um status bloqueado exige um motivo nas notas — senão o bloqueio não vale nada.
• 🗑️ Exclusão requer --yes e confirmação explícita do usuário. Não há status "cancelado" por padrão — se um for necessário, adicione-o ao esquema em vez de excluir.
• 📜 Cada alteração é registrada em item_history — nunca edite o DB manualmente.
• 🔁 Três ou menos status sem responsável e sem data de vencimento = deveria ser um registry.