ropimen/claude-skill-kpi-calculator

KPI-Rechner

Wandelt eine oder mehrere CSV/TSV-Dateien plus eine kurze Anweisung in einen verifizierten Satz von KPIs um, jeder mit Wert, Einheit, Gleichung, Bedeutung und Basisbezeichnung. Es gibt keine feste Liste von Feldern: KPIs werden für das entworfen, was die Daten und die Anweisung beschreiben. Papiere, Berichte oder frühere Ergebnisse, die neben den Daten angehängt sind, steuern ihre KPIs bei, angewendet auf die Daten des Benutzers mit ihrer Herkunft.

<skill_dir> unten bedeutet den Ordner, der diese Datei enthält. Führen Sie Skripte als python <skill_dir>/scripts/<name>.py aus dem Arbeitsordner aus (siehe „Wohin die Ausgaben gehen") und übergeben Sie Datendateien mit absolutem Pfad.

Wenn python nicht gefunden wird (oder den Microsoft Store öffnet), verwenden Sie py -3 unter Windows oder python3 woanders in jedem unten stehenden Befehl. Überprüfen Sie dies einmal zu Beginn mit python --version.

Harte Regeln

1. Jede Zahl stammt aus Code, der auf den Dateien ausgeführt wird. Schätzen Sie niemals, runden Sie nicht nach Augenmaß und geben Sie keinen Wert im Fließtext an, der nicht in results.json steht.
2. Ausgeschlossene KPIs werden niemals berechnet und erscheinen nirgendwo außer in der einzigen Zeile „Auf Ihren Wunsch ausgeschlossen".
3. Jede Annahme wird angegeben in „Was ich verstanden habe" (Muster, Rollen, Einheiten, Interpolation, Zeitzone, Tag/Monat-Reihenfolge, verwendete Standardwerte).
4. Höchstens eine Frage pro Durchlauf, und nur dann, wenn eine falsche Annahme die Ergebnisse ändern würde (siehe references/role-mapping.md, „Wann fragen"). Geben Sie andernfalls die getroffene Lesart an und fahren Sie fort.
5. Jeder KPI ist eine Spezifikation in kpi_specs.json, aufgebaut aus Grundelementen. Jeder ist gekennzeichnet als basis: established (Standard im Fachgebiet) oder derived (aus ersten Prinzipien abgeleitet).
6. Verhältnisse über Zeiträume sind Verhältnisse von Summen, nicht Mittelwerte von Verhältnissen, es sei denn, der KPI ist anders definiert.
7. Unregelmäßige Zeit ist Echtzeit. Zählen Sie niemals Zeilen als Zeitschritte; integrieren und mitteln Sie über Zeitstempel mit der Interpolation jeder Spalte.
8. Validierungsfehler werden einmalig überprüft (Parsenotizen → Mapping → Spezifikation), dann mit der Warnung gemeldet, niemals versteckt.
9. Fachwissen lebt nur in Markdown. Fügen Sie niemals feldspezifische Logik zu Skripten hinzu.
10. Werte aus Referenzen sind Zitate. Zahlen, die in Papieren oder früheren Ergebnissen gemeldet werden, gehen nur in das reference.reported einer Spezifikation ein; sie sind niemals Eingaben für eine Berechnung und werden niemals als das Ergebnis des Benutzers präsentiert.

Wohin die Ausgaben gehen

Entscheiden Sie dies in Schritt 1 und notieren Sie es in request.json → output_dir.

Situation	Arbeitsordner (alle JSON-Dateien, aktuelles Verzeichnis der Skripte)	Liefergegenstände
Der Benutzer nennt einen Ordner („Speichern Sie die Ergebnisse in D:/reports/line3")	Dieser Ordner (erstellen)	Gleicher Ordner
Claude-Apps (claude.ai / Desktop-Chat, /mnt/user-data/outputs/ existiert)	Das aktuelle Verzeichnis	Kopie in /mnt/user-data/outputs/: erscheinen als herunterladbare Dateien
Claude Code, kein Ordner genannt	kpi_output/ im aktuellen Verzeichnis	Gleicher Ordner

Liefergegenstände sind report.md, kpi_results.csv, kpi_run.py und, wenn erstellt, kpi_chart.png, kpi_adhoc.py sowie ein angebotenes Feldpaket. Die Arbeitsdateien (request.json, profile.json, mapping.json, kpi_specs.json, results.json) bleiben zur Prüfung im Arbeitsordner und werden nur auf Anfrage geteilt.

Übergeben Sie die Liefergegenstände an den Benutzer, damit er sie überall speichern kann:

• Claude-Apps: Neben den herunterladbaren Dateien zeigen Sie den fertigen Bericht als Markdown-Dokument-Artefakt an, damit er gelesen, kopiert oder separat heruntergeladen werden kann.
• Claude Code: Listen Sie jeden Liefergegenstand als Link zu seinem Pfad auf. Wenn der Host ein Werkzeug zum Senden von Dateien an den Benutzer anbietet (z. B. Dateikarten in der Desktop-App), senden Sie die Liefergegenstände ebenfalls darüber.
• Schreiben Sie niemals außerhalb des Arbeitsordners und des Ablageorts der Liefergegenstände, es sei denn, der Benutzer fragt danach.

Um kpi_run.py später erneut auszuführen, legen Sie es zusammen mit den Eingabedateien in einen Ordner.

Zuerst Skripte, Ad-hoc nur als Rückfall

Führen Sie immer die folgenden Skripte aus. Schreiben Sie Ihren eigenen Pandas-Code nur wenn:

• ein Skript mit einem Fehler beendet wird, den Sie nicht durch Korrektur von profile.json, mapping.json oder den Spezifikationen beheben können (z. B. eine Datei profile_csv.py kann nicht geparst werden), oder
• ein KPI eine Operation benötigt, die kein Grundelement oder Ausdruck abdeckt (check_spec.py meldet unknown_op).

Dann:

1. Fügen Sie den Code in kpi_adhoc.py im Arbeitsverzeichnis ein, laden Sie Daten mit den Parse-Einstellungen in profile.json (oder scripts/lib/io.py load) und halten Sie ihn eigenständig ausführbar.
2. Fügen Sie jeden Ad-hoc-KPI zu results.json → kpis mit jedem Feld von schemas/results.schema.json und "computed_by": "ad_hoc" hinzu, nachdem run_specs.py die Datei geschrieben hat. Ändern Sie niemals Werte, die die Engine berechnet hat.
3. Der Bericht markiert diese KPIs mit † und verweist auf kpi_adhoc.py.

Verwenden Sie niemals eval/exec auf benutzer- oder datenabgeleiteten Zeichenfolgen, auch nicht ad-hoc.

Arbeitsablauf

Führen Sie die acht Schritte in der Reihenfolge aus. Lesen Sie eine Referenzdatei nur, wenn ihr Schritt sie benötigt.

Schritt 1 [Claude] Anfrage parsen → request.json

Lesen Sie references/request-parsing.md. Extrahieren Sie field, mode, focus, include, exclude, custom, params, max_kpis, output_dir.

• Referenzen (Papiere, Berichte, Standards, frühere Ergebnisse), die in der Eingabeaufforderung angehängt oder genannt werden: Lesen Sie references/reference-documents.md, unterscheiden Sie sie von Datendateien, lesen Sie jede vollständig und notieren Sie ihre KPIs in request.json → references (ID, Name, Definition, Gleichung, Ort, gemeldete Werte). Nur Datendateien gehen zu Schritt 2.

• Excel-Eingabe: Konvertieren Sie jedes Blatt zuerst in ein eigenes CSV (pandas.read_excel(sheet_name=None)), benennen Sie sie <Buch>__<Blatt>.csv.

• Ein KPI, der sowohl eingeschlossen als auch ausgeschlossen ist → dies ist die eine Frage des Durchlaufs. Berechnen Sie nichts für diesen KPI, bis die Antwort vorliegt.

Schritt 2 [Skript] Laden und profilieren → profile.json

python <skill_dir>/scripts/profile_csv.py DATEI [DATEI ...] --out profile.json

Überprüfen Sie Typ, Einheitenhinweis und Parsenotizen jeder Spalte. Wenn eine Spalte, die numerisch sein sollte, als text ausgegeben wurde, sehen Sie sich ihre Stichproben an und korrigieren Sie das Parsen, bevor Sie fortfahren.

Schritt 3 [Skript] Zeit- und Sammlungsmuster erkennen → profile.json (Zeitabschnitt)

python <skill_dir>/scripts/detect_time.py --profile profile.json [--tz <IANA-Zeitzone>] --out profile.json

Lesen Sie references/collection-patterns.md. Das Skript schlägt ein Muster mit evidence und anderen plausiblen candidates vor, plus entity_column (wenn sich Zeitstempel über eine Gruppierungsspalte wiederholen), frequency (Pandas-Alias wie D, B, h, MS), gaps, duplicates und tz. Bestätigen oder überschreiben Sie das Muster und die Entität mithilfe der Beschreibung des Benutzers. Wenn ambiguous_dayfirst wahr ist, geben Sie die Annahme an (oder fragen Sie, wenn beide Lesarten die KPI-Werte ändern und keine andere Frage aussteht). Übergeben Sie --tz, wenn der Benutzer die Zeitzone von naiven lokalen Zeitstempeln nennt.

Schritt 4 [Claude] Spaltenrollen zuordnen → mapping.json

Lesen Sie references/role-mapping.md. Weisen Sie jeder Spalte eine Rolle, physikalische Größe, Einheit und Interpolation zu; notieren Sie Entität, Paare, Verknüpfungen, Umformung, Resampling und Parameter. Kopfzeilen in jeder Sprache werden nach Bedeutung gelesen; behalten Sie die ursprünglichen Namen.

Schreiben Sie dann mapping.json → sensitivity: eine Variante für jede Beurteilungsentscheidung, die vernünftigerweise auch anders hätte ausfallen können (Interpolation, eine mehrdeutige Zustandsklasse, Tag/Monat-Reihenfolge, geplante Ausfallzeiten, eine angenommene Einheit oder ein Parameter). Die Engine führt jeden KPI unter jeder Variante erneut aus und meldet einen Niedrig-Hoch-Bereich, sodass der Benutzer sieht, welche Zahlen von welchen Annahmen abhängen. Regeln und Patch-Format finden Sie in references/role-mapping.md, „Sensitivitätsvarianten".

Schritt 5 [Claude] KPIs entwerfen und auswählen → kpi_specs.json

Lesen Sie references/kpi-discovery.md (Methode) und references/kpi-spec.md (Format, Grundelemente, Grammatik). Wenn references/fields/ ein Paket enthält, das zum Feld passt, lesen Sie es ebenfalls; es informiert, aber schränkt niemals ein.

Auswahlreihenfolge: Erforderliche (include) und custom zuerst → KPIs aus references (Spezifikation source: reference mit einem reference-Block, siehe references/reference-documents.md) → niemals exclude → nach Relevanz für focus, etabliert vor abgeleitet, keine nahen Duplikate → begrenzen Sie Claudes eigene Auswahl auf max_kpis (Standard 12). Erforderliche, benutzerdefinierte und Referenz-KPIs werden niemals fallengelassen; ein Referenz-KPI, den die Daten nicht unterstützen können, erhält keine Spezifikation und wird unter „Nicht automatisch berechnet" aufgeführt.

Überprüfen Sie dann die Spezifikationen:

python <skill_dir>/scripts/check_spec.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json

Exit 0 = ok. Exit 1 = Fehler als JSON auf stdout: korrigieren Sie die Spezifikation oder das Mapping und führen Sie es erneut aus. Unbekannte Einheiten kommen als Warnungen zurück: Wenn eine die Ergebnisse ändert, kann dies die Frage des Durchlaufs sein.

Schritte 6–7 [Skript] Berechnen und validieren → results.json, kpi_run.py

python <skill_dir>/scripts/run_specs.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json --out results.json --script-out kpi_run.py

Jede Spezifikation wird pro Gruppe (Entität) plus einem Gesamtwert nach ihrer overall-Regel ausgeführt. Eine fehlschlagende Spezifikation oder Gruppe wird not_computed mit ihrem Grund; der Durchlauf wird fortgesetzt. Die stdout-Zusammenfassung listet jede validation:-Warnung auf.

Derselbe Durchlauf:

• führt alle KPIs einmal pro Sensitivitätsvariante erneut aus und speichert sensitivity: {low, high, variants} auf jedem KPI;
• vergleicht jeden KPI mit den Werten, die seine Referenzen melden, umgerechnet in die Einheit des KPI (comparison: Differenz, relative Differenz, besser/schlechter nach Richtung, ob der gemeldete Wert innerhalb des Sensitivitätsbereichs liegt);
• schreibt data_health: pro zugeordneter numerischer Spalte, fehlender Anteil, längster konstanter Lauf, robuste Ausreißer und unmögliche Werte (negative Zählungen, % über 100, unter absolutem Nullpunkt), plus Zeitabdeckung für regelmäßige Reihen.

Wenn ein KPI eine Validierungswarnung trägt: Überprüfen Sie Parsenotizen (Schritt 2), Mapping (Schritt 4) und Spezifikation (Schritt 5) einmal, führen Sie es ab dem frühesten geänderten Schritt erneut aus, melden Sie es dann mit der Warnung, wenn es immer noch fehlschlägt.

Nach dem Durchlauf dürfen Sie results.json nur bearbeiten, um einen enable-Text zu not_computed-Einträgen hinzuzufügen (immer für KPIs aus Referenzen und include) (welche Daten oder Parameter den KPI berechenbar machen würden) und, gemäß dem obigen Rückfall, Ad-hoc-KPI-Datensätze. kpi_run.py bettet die Hashes der Eingaben, das Profil, das Mapping, die Spezifikationen und den Code der Fähigkeit ein; es reproduziert results.json (als results_rerun.json) ohne die Fähigkeit.

Schritt 8 [Skript + Claude] Bericht → report.md, kpi_results.csv, optionales Diagramm

python <skill_dir>/scripts/report.py --results results.json --request request.json \
       --mapping mapping.json --profile profile.json \
       --out-md report.md --out-csv kpi_results.csv [--chart kpi_chart.png]

Übergeben Sie --chart nur, wenn der Fokus Veränderungen im Laufe der Zeit betrifft und eine Zeitspalte existiert; es zeichnet bis zu zwei KPIs mit per_period-Werten (geben Sie diesen KPIs einen per_period-Gültigkeitsbereich). Das Skript weigert sich auszuführen, wenn sich ein ausgeschlossener KPI in results.json befindet.

Lesen Sie references/report-format.md, ersetzen Sie dann die Platzhalter, die das Skript auf stdout auflistet, und bearbeiten Sie report.md direkt:

• {{FINDINGS}}: 2–5 Sätze, die den Fokus beantworten, unter Angabe von KPI-Werten mit Einheiten aus results.json. Keine neuen Zahlen. Nennen Sie KPIs, deren Sensitivitätsbereich groß ist (und die Lesart, die sie verschiebt), den Vergleich mit Referenzen, falls vorhanden (unter Verwendung der berechneten Differenz und des Urteils, mit den Grenzen der Vergleichbarkeit), und jede Datenqualitätsmarkierung für eine Spalte, die ein Schlüssel-KPI verwendet.
• {{READING:<kpi_id>}}: ein Satz pro KPI: gut oder schlecht relativ zu seiner Richtung und typischem Bereich, falls bekannt.

Alles andere im Bericht (Namen, Gleichungen, Bedeutungen, Zahlen) stammt aus results.json und wird nicht umgeschrieben. Zeigen Sie den fertigen report.md im Chat an und liefern Sie die Dateien wie in „Wohin die Ausgaben gehen" beschrieben.

Ausgabe-Checkliste

Bestätigen Sie vor der Antwort alle folgenden Punkte:

• Chat-Bericht mit den acht Abschnitten in der Reihenfolge: Was ich verstanden habe · KPI-Übersicht · KPI-Details · Ergebnisse · Nicht berechnet · Auf Ihren Wunsch ausgeschlossen · Datenprobleme · Reproduzieren.
• Jeder KPI zeigt Wert, Einheit, Richtung, Basisbezeichnung, Quelle, LaTeX-Gleichung und Klartext-Gleichung, Symbole, die den ursprünglichen Spaltennamen mit n zugeordnet sind, Bedeutung, Lesart, Warnungen.
• Jeder erforderliche KPI ist entweder berechnet oder unter „Nicht berechnet" mit den Daten oder Parametern aufgeführt, die ihn ermöglichen würden.
• Kein ausgeschlossener KPI erscheint irgendwo außer in der einen „Ausgeschlossen"-Zeile (überprüfen Sie auch die CSV).
• Sammlungsmuster und jede Annahme angegeben; jede Beurteilungsentscheidung entweder gefragt oder angegeben und als Sensitivitätsvariante getestet.
• Datenqualitätstabelle vorhanden; Flags zu Eingaben von Schlüssel-KPIs in den Ergebnissen erwähnt.
• Jeder in einer Referenz gefundene KPI ist entweder berechnet (mit Zitat, Ort, Definition und Anpassung gezeigt) oder unter „Nicht berechnet" mit dem aufgeführt, was ihn ermöglichen würde; gemeldete Werte sind als zitiert gekennzeichnet.
• kpi_results.csv (UTF-8 mit BOM) und kpi_run.py geschrieben, und jeder Liefergegenstand gemäß „Wohin die Ausgaben gehen" an den Benutzer übergeben (Downloads + Berichtsartefakt in Claude-Apps; Pfade und Dateikarten in Claude Code).
• Diagramm nur, wenn der Fokus Veränderungen im Laufe der Zeit betrifft.
• Feld ohne Paket in references/fields/: Bieten Sie ein Feldpaket an, das aus den in diesem Durchlauf verwendeten KPIs aufgebaut ist, als separate Markdown-Datei nach references/fields/_template.md, damit der Benutzer es überprüfen und hinzufügen kann. Schreiben Sie es nicht in den Fähigkeitsordner.

Nicht-Ziele

Keine Prognose oder Modellbildung (die Fähigkeit bewertet ihr gegebene Vorhersagen). Keine Live-Feeds oder Datenbanken. Keine Anlage-, Medizin- oder Ingenieurberatung: Melden Sie Metriken und was sie anzeigen. Keine Währungsumrechnung: Gemischte Währungen werden gekennzeichnet und pro Währung berechnet.

Standardwerte (ohne Nachfragen verwenden, bei Verwendung angeben)

Einstellung	Standard
Risikofreier Zinssatz	0
Annualisierungsfaktor	werktags täglich 252, kalendertäglich 365, wöchentlich 52, monatlich 12, vierteljährlich 4, stündlich 8760
MASE saisonale Periode	stündlich 24, täglich 7, wöchentlich 52, monatlich 12, vierteljährlich 4, sonst 1
Unregelmäßigkeitsschwelle	Intervall-CV > 0.5
Lückenschwelle	3 × Medianintervall
Zeitspalten-Parse-Rate	≥ 95%
Profil-Stichprobe	> 1.000.000 Zeilen → 200.000-Zeilen-Stichprobe (Zeitspalte immer vollständig gelesen)
max_kpis	12 (nur Claudes eigene Auswahl)
Prozentbehandlung	0–100 Werte in einer Spalte, deren he...

… [für die Übersetzung gekürzt]