Avishai-Tsabari/mercury-skills

Tracker – Arbeit verfolgen, die sich bewegt

Wann dieser Skill der richtige ist

Leitfrage: „Wie ist der Status von…?“ oder „Wer besitzt das?“

Ein Tracker = Elemente, die sich zwischen Zuständen bewegen, mit Besitzer und Zeitplan, und mit Historie, die es wert ist, erhalten zu bleiben.

Der Routing-Test

Sie benötigen mindestens zwei dieser Kriterien, um einen Tracker zu rechtfertigen:

• Ein Status, der sich im Laufe der Zeit ändert (kein Attribut – Bewegung)
• Ein menschlicher Bearbeiter
• Ein Fälligkeitsdatum
• Eine Hierarchie: Gruppe → Untergruppe → Element

Weniger als zwei? → registry. ⚠️ Der Standard ist immer Registry.

Wie es gebaut ist

Ein Motor, viele Schemas.

<tracker-verzeichnis>/
  schema.json    Status, Prioritäten, Hierarchiebezeichnungen, zusätzliche Felder
  tracker.db     SQLite: Elemente + Gruppen + Element_Historie

Motor: engine/tracker.py (neben dieser SKILL.md) · Python 3.9+ · keine Abhängigkeiten (eingebautes sqlite3).

Hierarchie: Gruppe → Untergruppe → Element. Die Bezeichnungen ändern sich pro Domäne – bei Aufgaben ist es Projekt → Modul → Aufgabe, bei Fehlern Produkt → Komponente → Fehler, bei Rechnungen Kunde → Abonnement → Rechnung.

Arbeiten mit dem Benutzer

1. Führen Sie den Routing-Test durch. Eine flache Liste → registry.
2. Schlagen Sie ein Schema vor: welche Status, was als „geschlossen“ gilt, welche Prioritäten, wie die Hierarchie aussieht, welche zusätzlichen Felder nötig sind. Präsentieren Sie es und bitten Sie um Zustimmung.
3. Suchen Sie nach einer Voreinstellung in presets/.
4. Erstellen Sie mit init, fügen Sie Gruppen hinzu, dann registrieren Sie den Tracker im Arbeitsbereichs-Index registries.json.
5. Erklären Sie, dass Updates in natürlicher Sprache gemeldet werden können – der Agent übersetzt sie in Befehle.

Befehle

Pfade sind relativ zum Arbeitsbereichs-Stammverzeichnis. Passen Sie SKILL_DIR an den Ort an, an dem dieser Skill installiert ist (z. B. .pi/skills/tracker).

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

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 "Doppelbuchung im Kalender" --group webapp --subgroup checkout \
        --assignee dana --priority sev2 --client acme --due 2026-08-05
python3 $T --dir $D update 3 --status in-progress --notes "reproduziert"
python3 $T --dir $D list --assignee dana --group-by status
python3 $T --dir $D list --status blocked
python3 $T --dir $D show 3
python3 $T --dir $D history 3
python3 $T --dir $D report          # Zusammenfassung: nach Status, nach Bearbeiter, überfällig, blockiert
python3 $T --dir $D delete 3 --yes  # ⚠️ endgültige Löschung

list ohne Filter blendet standardmäßig geschlossene Elemente aus. --all zeigt alles.

Verfügbare Voreinstellungen

tasks Aufgaben · bugs Fehler und Kundenprobleme · invoices Rechnungen und Mahnwesen · features Feature-Pipeline

Reihenfolge der Voreinstellungsauflösung

init --preset <name> löst <name>.json in dieser Reihenfolge auf – der erste Treffer gewinnt:

1. <workspace>/trackers/presets/<name>.json – arbeitsbereichs-lokale Voreinstellungen, relativ zum Arbeitsverzeichnis, von dem der Motor ausgeführt wird
2. <SKILL_DIR>/presets/<name>.json – die oben aufgeführten integrierten Voreinstellungen

Eine arbeitsbereichs-lokale Voreinstellung mit demselben Namen wie eine integrierte überschattet diese. Eine fehlende Voreinstellung listet jeden verfügbaren Namen von beiden Orten auf, gekennzeichnet mit [space] / [built-in].

Erstellen einer arbeitsbereichs-lokalen Voreinstellung: Legen Sie ein Schema-JSON (gleiches Format wie schema.json, siehe die integrierten Voreinstellungen für Beispiele) in trackers/presets/ ab. Das Verzeichnis wird nur bei einem expliziten --preset <name> gelesen – andere Dateien dort werden ignoriert.

Eiserne Regeln

• 📊 Der Tracker ist die Quelle der Wahrheit – bewahren Sie Status niemals im Gedächtnis des Agenten auf. Führen Sie immer Abfragen durch.
• ⛔ Ein blocked-Status erfordert einen Grund in den Notizen – sonst ist die Blockierung wertlos.
• 🗑️ Löschung erfordert --yes und explizite Benutzerbestätigung. Es gibt standardmäßig keinen Status „abgebrochen“ – falls einer benötigt wird, fügen Sie ihn zum Schema hinzu, anstatt zu löschen.
• 📜 Jede Änderung wird in item_history aufgezeichnet – bearbeiten Sie die Datenbank niemals von Hand.
• 🔁 Drei oder weniger Status ohne Bearbeiter und ohne Fälligkeitsdatum = es hätte ein Registry sein sollen.