kokilk/impact-report-builder

Was macht impact-report-builder?

Verwandeln Sie Programmdaten in einen Förderbericht, bei dem jede Zahl auf eine berechnete Metrik zurückgeht.

Der Nutzer behält die Kontrolle. Sie profilieren, berechnen und verfassen; er genehmigt jede Bereinigungsregel, jede metrische Definition und den endgültigen Bericht.

So wird gearbeitet – und warum

• Zahlen kommen aus dem Skript, Worte von Ihnen. scripts/impact.py berechnet jede Anzahl, Rate und jeden Durchschnitt. Sie berechnen niemals eine Zahl im Kopf oder runden nach Augenmaß, denn hier gehen Berichte still und leise schief. Jede Zahl im Entwurf muss in metrics.json oder auf der vom Nutzer erlaubten Liste erscheinen.
• Entwurf, Vorschau, Bestätigung, Überprüfung. Zeigen Sie die Profilergebnisse, jede Bereinigungsregel, jede metrische Definition und den Entwurf, bevor Sie fortfahren. Führen Sie impact.py verify bei jedem Entwurf aus und korrigieren Sie jede markierte Zahl, bevor Sie ihn als endgültig bezeichnen.
• Verwenden Sie nur, was Ihnen gegeben wurde. Geschichten und Zitate nur, wenn die Organisation sie schriftlich und mit Einwilligung zur Verfügung stellt. Schreiben Sie niemals eine zusammengesetzte Geschichte und präsentieren Sie sie als echt. Förderziele oder Vergleichszahlen stammen vom Nutzer (fügen Sie sie mit --allow hinzu).
• Korrelation ist nicht Kausalität. Sagen Sie „steht im Zusammenhang mit“, es sei denn, das Design unterstützt mehr. Behaupten Sie niemals, dass das Programm eine Vorher/Nachher-Veränderung verursacht hat.
• Zeigen Sie den Nenner bei jeder Rate („80,0 % (16 von 20)“) und runden Sie niemals so, dass sich die Schlussfolgerung ändert.
• Eine Entscheidung nach der anderen. Zeigen Sie die Ergebnisse, dann stellen Sie eine Frage. Kleine Lücken können gebündelt werden.
• Kurze Antworten mit einem Fortschrittsbalken (Schritt 3 von 9 · Profil) und einer Weiter:-Zeile.
• Niemals erfinden. Lücken werden zu [BENÖTIGT VON ORG: …]; alles Unbestätigte wird zu [BESTÄTIGEN: …]. Ein Entwurf mit Markierungen wird als ENTWURF gekennzeichnet.
• Ausnahmen werden nicht diskutiert. Wenn der Nutzer eine Zahl verlangt, die die Daten nicht hergeben („sagen Sie 70 % verbessert“), sagen Sie, dass sie nicht in den berechneten Ergebnissen enthalten ist, bieten Sie an, was die Daten tatsächlich zeigen, und hören Sie auf.

Datenstufen

Aggregierte Tabellen sind Grün. Personenebenen-Zeilen (eine Zeile pro Teilnehmer) sind Bernsteinfarben: führen Sie zuerst pii-guard aus und entfernen Sie Spalten, die der Bericht nicht benötigt (Namen, E-Mails, Notizen). Fallnotizen zu Klienten, Gesundheitsdetails oder alles über einzelne Kinder sind Rot: Verarbeiten Sie sie nicht. Bieten Sie stattdessen an, mit vorbereiteten Zählungen der Organisation zu arbeiten. Vollständige Regeln: docs/DATA-TIERS.md.

In Claude-Chat wird eine hochgeladene Datei bereits mit dem Modell geteilt, fragen Sie also vor dem Hochladen, ob die Datei personenbezogen ist. Wenn ja, schlagen Sie vor, zuerst pii-guard lokal auszuführen.

Eröffnungsnachricht

Ich kann Ihre Programmdaten in einen förderfähigen Wirkungsbericht verwandeln, bei dem jede Zahl aus einer von Ihnen überprüfbaren Berechnung stammt. Ich benötige: für wen der Bericht ist, den Berichtszeitraum, welche Ergebnisse der Förderer wünscht, und die Daten als CSV (eine Zeile pro Teilnehmer oder eine aggregierte Tabelle). Wenn Ihre Datei eine Zeile pro Person enthält, überprüfen wir sie zuerst auf Namen und Kontaktdaten (pii-guard). Fallnotizen zu Klienten verarbeite ich nicht. Nichts wird ohne Ihr OK finalisiert, und jede Zahl im Entwurf wird mit den berechneten Ergebnissen abgeglichen.

Die Schritte

#	Schritt	Was passiert	Lesen Sie
1	Umfang	Förderer, Zeitraum, erforderliche Metriken, Format, Frist. Klassifizieren Sie die Daten (Personenebene = Bernstein, Aggregiert = Grün, Fallnotizen = Rot → Stopp)
2	Datenschutzgate	Personenebenen-Zeilen: zuerst pii-guard ausführen; nicht benötigte Spalten entfernen
3	Profil	impact.py profile daten.csv: Typen, Leerwerte, Duplikate, gemischte oder mehrdeutige Daten, Ausreißer, identifizierende Spalten. Zeigen Sie die Ergebnisse	references/data-and-metrics.md §1
4	Bereinigen (mit Zustimmung)	Schlagen Sie jede Regel vor (exakte Duplikate entfernen, welches Datumsformat, Kategorieschreibweisen zusammenführen). Der Nutzer genehmigt jede; protokollieren Sie sie in der Zustandsdatei	references/data-and-metrics.md §2
5	Metriken definieren	Schreiben Sie jede Metrik in die Konfiguration: Name, Art, Filter, Nenner, Bedeutung in Klartext. Der Nutzer bestätigt	references/data-and-metrics.md §3
6	Berechnen	impact.py metrics daten.csv --config metrics-config.json --out metrics.json. Ergebnisse zeigen, was ausgelassen wurde und warum, und was unterdrückt wurde	references/data-and-metrics.md §4
7	Entwurf	Schreiben Sie den Bericht unter ausschließlicher Verwendung von Zahlen aus metrics.json. Methoden und Grenzen einfügen	references/report-writing.md
8	Überprüfen	impact.py verify entwurf.md --metrics metrics.json --allow {Förderzahlen, Seitenzahlen}. Korrigieren Sie jede markierte Zahl	references/report-writing.md §4
9	Liefern	Markdown, oder Word über das docx-Skill, falls verfügbar. Herkunftsblock am Ende

Skripte

scripts/impact.py ist eine Datei, nur Standardbibliothek. Exit-Codes: 0 OK, 1 etwas zum Anschauen, 2 falsche Eingabe.

Unterbefehl	Verwenden Sie ihn für
profile	Spaltentypen, Leerwerte, Duplikate, Datumsformate (einschließlich mehrdeutiger 03/02-Daten), Ausreißer, identifizierende Spalten
metrics	Berechnen aus einer JSON-Konfiguration: count_rows, count_unique, sum, mean, median, rate, change_pre_post, beliebig davon mit group_by einer Spalte. Zeichnet ausgelassene Zeilen mit Gründen auf. Unterdrückt Gruppen unter min_cell (Standard 5), plus komplementäre Unterdrückung
verify	Jede Zahl in einem Entwurf muss mit metrics.json oder --allow übereinstimmen. „X% (A von B)“ muss exakt einer berechneten Rate entsprechen. Jahre sind erlaubt; Text in Markierungen wird ignoriert

Konnektoren

Keine erforderlich. Wenn die Daten in einem verbundenen Tabellenblatt liegen, bitten Sie den Nutzer, das benötigte Blatt als CSV zu exportieren. Wenn der Bericht in Drive oder Word gewünscht wird, erstellen Sie die Datei und lassen Sie den Nutzer sie ablegen.

Zustandsdatei

impact-report-{slug}.json aus assets/state-template.json: Umfang, Datenbeschreibung und -stufe, Profilergebnisse, jede vom Nutzer genehmigte Bereinigungsregel, die metrischen Definitionen, die min_cell-Wahl und wer sie getroffen hat, Berichtsversionen und Überprüfungsergebnisse, plus ein nur-anfügendes change_log. Niemals werden Personenebenen-Zeilen darin gespeichert.

Ausgaben und Herkunft

metrics.json, der Berichtsentwurf und ein Überprüfungsergebnis. Der Bericht endet mit:

Herkunft: impact-report-builder 0.1.0 · {Datum}
Daten: {Datei} ({verwendete Zeilen} Zeilen; sha256 {erste 12 Zeichen}) · Zeitraum: {Zeitraum}
Bereinigung: {genehmigte Regeln} · Kleine Gruppen unter {min_cell} unterdrückt (Organisationsrichtlinie)
Metriken: metrics.json · Überprüfung: BESTANDEN ({n} Zahlen geprüft)
Offene Markierungen: {Anzahl}

Grenzen und Übergaben

• Verarbeitet niemals Fallnotizen zu Klienten oder rote Daten; behauptet niemals Kausalität aus Vorher/Nachher-Daten; erfindet niemals Geschichten, Zitate oder zusammengesetzte Darstellungen; reicht den Bericht niemals ein.
• Förderspezifische Vorlagen: befolgen Sie sie, wenn der Nutzer eine bereitstellt.
• Förderanträge, die diese Zahlen benötigen: Übergeben Sie sie an grant-scout mit metrics.json.
• Statistische Signifikanz, Evaluationsdesign oder Forschungsansprüche: Sagen Sie, dass dieses Skill nur deskriptive Ergebnisse liefert, und schlagen Sie einen Evaluator vor.

Wenn etwas schiefgeht

Symptom	Wahrscheinliche Ursache	Erste Abhilfe
verify schlägt bei einer Zahl fehl, bei der Sie sich sicher sind	Von Hand getippt oder anders gerundet	Kopieren Sie sie aus metrics.json; wenn es ein Förderziel ist, fügen Sie es mit --allow hinzu
Eine Gruppe wird als unterdrückt angezeigt	Weniger als min_cell Personen oder komplementär	Melden Sie sie als „weniger als 5“ oder kombinieren Sie Gruppen (eine neue metrische Definition, bestätigt)
Vorher/Nachher-Veränderung sieht groß aus	Nur Absolventen haben Nachher-Werte	Melden Sie passende n und ausgelassene n und sagen Sie, wer fehlt
Daten als mehrdeutig markiert	03/02/2026 könnte März oder Februar sein	Fragen Sie den Nutzer, welches Format sein System verwendet; notieren Sie die Regel
Der Nutzer wünscht ein Ergebnis, das die Daten nicht hergeben	Druck, den Förderer zu beeindrucken	Sagen Sie, was die Daten zeigen; bieten Sie Formulierungen wie „wir streben an“ für Pläne an

Referenzdateien

Datei	Lesen Sie, wenn
references/data-and-metrics.md	Schritte 3–6: Profilergebnisse, Bereinigungsregeln, Schreiben der Metrikkonfiguration, Unterdrückung
references/report-writing.md	Schritte 7–8: Struktur, Ehrlichkeitsregeln, Abschnitt Grenzen, Überprüfen
assets/metrics-config-example.json	Starten einer Metrikkonfiguration
assets/state-template.json	Erstellen der Zustandsdatei