Avishai-Tsabari/mercury-skills

Rastreador — siguiendo el trabajo que se mueve

Cuándo usar esta habilidad

Pregunta clave: "¿Cuál es el estado de...?" o "¿Quién es el responsable?"

Un rastreador = elementos que cambian de estado, con responsable, cronograma e historial que vale la pena preservar.

La prueba de enrutamiento

Necesitas al menos dos de estos para justificar un rastreador:

• Un estado que cambia con el tiempo (no un atributo — movimiento)
• Un responsable (persona asignada)
• Una fecha límite
• Una jerarquía: grupo → subgrupo → elemento

¿Menos de dos? → registro. ⚠️ El valor predeterminado es siempre registro.

Cómo está construido

Un motor, muchos esquemas.

<directorio-rastreador>/
  schema.json    estados, prioridades, etiquetas de jerarquía, campos adicionales
  tracker.db     SQLite: elementos + grupos + historial_de_elems

Motor: engine/tracker.py (junto a este SKILL.md) · Python 3.9+ · sin dependencias (sqlite3 integrado).

Jerarquía: grupo → subgrupo → elemento. Las etiquetas cambian según el dominio — para tareas es proyecto → módulo → tarea, para bugs es producto → componente → bug, para facturas es cliente → suscripción → factura.

Trabajando con el usuario

1. Realiza la prueba de enrutamiento. Una lista plana → registro.
2. Propón un esquema: qué estados, qué se considera "cerrado", qué prioridades, cuál es la jerarquía, qué campos adicionales. Preséntalo y solicita aprobación.
3. Verifica si hay un preajuste en presets/.
4. Crea con init, agrega grupos, luego registra el rastreador en el índice registries.json del espacio de trabajo.
5. Explica que las actualizaciones se pueden reportar en lenguaje natural — el agente las traduce a comandos.

Comandos

Las rutas son relativas a la raíz del espacio de trabajo. Ajusta SKILL_DIR a donde esté instalada esta habilidad (ej. .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 "Doble reserva en calendario" --group webapp --subgroup checkout \
        --assignee dana --priority sev2 --client acme --due 2026-08-05
python3 $T --dir $D update 3 --status en-progreso --notes "reproducido"
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          # resumen: por estado, por responsable, vencidos, bloqueados
python3 $T --dir $D delete 3 --yes  # ⚠️ eliminación permanente

list sin filtro oculta automáticamente los elementos cerrados. --all lo muestra todo.

Preajustes disponibles

tasks tareas · bugs bugs e incidencias de clientes · invoices facturas y cobranza · features pipeline de funcionalidades

Orden de resolución de preajustes

init --preset <nombre> resuelve <nombre>.json en este orden — el primero que coincide gana:

1. <espacio-de-trabajo>/trackers/presets/<nombre>.json — preajustes locales del espacio, relativos al directorio de trabajo desde donde se ejecuta el motor
2. <SKILL_DIR>/presets/<nombre>.json — los preajustes integrados listados arriba

Un preajuste local del espacio con el mismo nombre que uno integrado lo reemplaza. Si falta un preajuste, se listan todos los nombres disponibles de ambas ubicaciones, etiquetados [espacio] / [integrado].

Creación de un preajuste local del espacio: coloca un esquema JSON (mismo formato que schema.json, consulta los integrados para ejemplos) en trackers/presets/. El directorio solo se lee en un --preset <nombre> explícito — otros archivos allí se ignoran.

Reglas de hierro

• 📊 El rastreador es la fuente de verdad — nunca mantengas estados en la memoria del agente. Siempre consulta.
• ⛔ Un estado bloqueado requiere una razón en las notas — de lo contrario, el bloqueo no tiene valor.
• 🗑️ La eliminación requiere --yes y confirmación explícita del usuario. No hay estado "cancelado" por defecto — si se necesita uno, agréguelo al esquema en lugar de eliminar.
• 📜 Cada cambio se registra en item_history — nunca edites la base de datos manualmente.
• 🔁 Tres estados o menos sin responsable y sin fecha límite = debería haber sido un registro.