DELTA37/structured-report

Strukturierter Bericht

Eine eigenständige HTML-Datei (kein Netzwerk), die einem vielbeschäftigten Leser ermöglicht:

1. die gesamte Arbeit als Aufgabenkarte zu sehen, mit dem, was darin auf ihn wartet,
2. jede Aufgabe – und jede darin enthaltene Stufe – zu öffnen und zu prüfen, wie sie erledigt wurde und warum jede Behauptung für glaubwürdig gehalten wird,
3. die Fragen des Agenten direkt dort zu beantworten und zu sehen, welche seiner Eingabeaufforderungen was bewirkt haben.

Struktur vs. Inhalt

• Struktur gehört zur Vorlage (assets/template.html): Layout, Abschnittsnamen (Problem, Aufgabe, Kontext, Schlussfolgerungen, Annahmen, Ergebnis, Nicht geprüft, Arbeitsablauf, Genehmigung erforderlich, Ihre Aktionen), deren Reihenfolge, Status, jedes Symbol und jede UI-Beschriftung. Fest, immer Englisch. Symbole kennzeichnen nur die Struktur, niemals den Inhalt.
• Inhalt gehört Ihnen: das JSON in der Sprache des Benutzers. scripts/build.py validiert es und füllt die Platzhalter der Vorlage. Sie schreiben niemals HTML und erfinden keine Abschnitte.

Arbeitsablauf

1. Material sammeln: Nachrichten, Tool-Ergebnisse, Dateien, Befehle, Links, Tests, Messungen, Entscheidungen. Berichten Sie nur, was tatsächlich passiert ist.
2. In Aufgaben aufteilen (1–12): eine Aufgabe = ein Ziel mit eigenem Ergebnis. Verbinden Sie sie mit links: depends, blocks, related.
3. Jede Aufgabe befüllen gemäß den folgenden Regeln und references/schema.md.
4. JSON schreiben — Standardmäßig reports/<YYYY-MM-DD>-<slug>.json im Arbeitsverzeichnis.
5. Erstellen: python3 <skill>/scripts/build.py <datei>.json → <datei>.html. Beheben Sie jeden error:; lesen Sie jede warning: und beheben Sie sie, es sei denn, sie ist wirklich zutreffend.
6. Lokal öffnen (open / xdg-open / start) und den Pfad angeben. Niemals hochladen.
7. Im Chat: 2–4 Zeilen – das wichtigste Ergebnis und was auf den Leser wartet.

Lebender Bericht: Sitzung verfolgen, Antworten zurücknehmen

Wenn der Benutzer möchte, dass der Bericht während der Sitzung aktuell gehalten wird (oder einen verfolgten / lebenden Bericht anfordert), binden Sie die Sitzung einmal:

python3 <skill>/scripts/track.py start reports/<datei>.json      # erzeugt <datei>.journal.json

Ab dann protokolliert der UserPromptSubmit-Hook (einmal installieren: track.py install-hook, der auch den Stop-Hook hinzufügt) jede Benutzereingabe im Journal und erinnert Sie an die Eingabeaufforderungsnummer. Nach jeder Eingabeaufforderung, die die Arbeit ändert, JSON aktualisieren und neu erstellen – build.py erstellt Fingerabdrücke für jeden Block (jeder Knoten × Abschnitt) und kennzeichnet neue oder geänderte Blöcke mit der aktuellen Eingabeaufforderung. Schreiben Sie niemals selbst Stempel. Der Bericht zeigt eine Eingabeaufforderungsleiste; die Auswahl einer Eingabeaufforderung hebt hervor, was dort erschienen (grün) oder geändert (blau) ist.

Fragen an den Leser. Entscheidungen in approvals ablegen. Jede ist eine Frage mit options – standardmäßig exklusiv (eine Antwort) oder "multi": true (alle zutreffenden) – Ihre recommend (eine Liste für Multi-Auswahl), why und due. Der Leser hat immer „Ihre eigene Antwort“ als zusätzliche Option; eine Frage ohne Optionen wird im Freitext beantwortet. Im Bericht bilden die offenen Fragen eines Genehmigung erforderlich-Abschnitts eine Serie, eine Frage nach der anderen: Eine exklusive Option beantwortet und fährt fort, eine Mehrfachauswahl oder eigene Antwort wird mit „Weiter“ bestätigt, die Serie endet mit einer Überprüfung aller Antworten, und Antworten senden sendet sie an Sie – es gibt keine andere Möglichkeit zu senden, und actions (vom Leser durchgeführte Schritte) haben keine Eingaben. Die Antworten gehen an einen lokalen Antwortdienst (127.0.0.1:47319, gestartet und vom Build auf dem neuesten Stand gehalten), selbst wenn der Bericht als normale Datei geöffnet wird, und werden im Journal als nächste Eingabeaufforderung gespeichert. Solange der Bericht offene Fragen hat, lassen Sie einen Wartevorgang als Hintergrund-Befehl laufen:

python3 <skill>/scripts/track.py wait reports/<datei>.json

Wenn der Leser sendet, gibt wait die Antworten aus und beendet sich – diese Ausgabe kommt zu Ihnen zurück: Behandeln Sie sie genau wie die Eingabeaufforderung des Benutzers und fahren Sie fort; starten Sie wait erneut, wenn noch Fragen offen sind. Wenn kein Wartevorgang läuft, übergibt der Stop-Hook die in der Warteschlange befindlichen Antworten, bevor Ihre Runde endet, und der UserPromptSubmit-Hook hängt sie an die nächste Nachricht des Benutzers an – Antworten gehen nie verloren. Beantwortete Fragen werden nach dem nächsten Build als beantwortet angezeigt. --static erstellt einen Bericht ohne Antwortkanal (zum Teilen außerhalb dieses Rechners): Fragen werden schreibgeschützt ohne Eingabefelder angezeigt.

Link unter der Eingabe. scripts/statusline.py gibt eine Statuszeile für den Sitzungsbericht aus – seinen Titel als klickbaren Link, der das HTML im Browser öffnet, und wie viele Fragen noch warten. Verwenden Sie es als Statuszeile oder hängen Sie seine Ausgabe an eine vorhandene an; es gibt nichts für Sitzungen ohne Bericht aus.

Jeder Block des Berichts hat eine Als Markdown kopieren-Schaltfläche (den gesamten Bericht, eine Aufgabenkarte, einen Bericht, einen Abschnitt, ein einzelnes Element, einen Schritt, eine Eingabeaufforderung) – weisen Sie den Leser darauf hin, wenn er etwas woanders einfügen möchte.

Die Regeln, die den Bericht vertrauenswürdig machen

Trennen Sie wie Sie etwas wissen; verschwimmen Sie es nie.

• kontext – Quellen, die Sie tatsächlich angesehen haben: id (C1…), kurzer title, eine echte url und eine note mit der genauen Tatsache. Erfinden Sie niemals URLs. Bevorzugen Sie Repo-/Web-URLs: file://-Links öffnen sich nicht auf dem Rechner des Lesers (Build warnt; eine fehlende lokale Datei ist ein Fehler).
• schlussfolgerungen – Schlussfolgerungen, jede mit basis (Kontext-IDs) und confidence. Keine Basis → es ist eine Annahme.
• annahmen – als wahr angenommen ohne Prüfung: why, wie zu verify, risk bei Fehler.
• nicht-geprüft – was Sie nicht geprüft oder getan haben, mit why nicht. Leser verlassen sich darauf mehr als auf alles andere; sagen Sie es klar. Eine erledigte Aufgabe ohne unchecked erhält eine Warnung ([] bedeutet „alles geprüft“ – nur wenn wahr).
• ergebnis – was jetzt existiert, als typisierte Elemente. Jedes verified-Element benötigt how: den Befehl, Test oder Link, der es beweist – der Build schlägt ohne fehl.
• stufen – die Schritte, die Sie tatsächlich unternommen haben, 2–8 pro Ebene. Eine Stufe ist die gleiche Art von Knoten wie eine Aufgabe: id + title erforderlich, jedes Aufgabenfeld erlaubt, eigene stages + flow, bis zu jeder Tiefe. Auf der Karte zeigt es detail (was Sie getan haben), outcome (was dabei herauskam), status, when, uses. Wenn Sie auf eine Stufe klicken, öffnet sich ihr Bericht in der gleichen Struktur. Geben Sie echte Inhalte für Stufen, die echte Arbeit waren. Sackgassen sind auch Stufen (failed / skipped).
• nächste Schritte sind geplante Stufen – alles, was noch zu tun ist, ist eine Stufe mit status: "planned", einem detail (was getan wird) und when (die Bedingung oder Zeit: „nach Ihrer Genehmigung“, „Montag“). Eine unvollendete Aufgabe ohne geplante oder laufende Stufe erhält eine Warnung.
• genehmigungen – Entscheidungen, die nur der Leser treffen kann: die Frage, why sie ihm obliegt, options (exklusiv oder multi: true), Ihre empfehlung (eine der Optionen; eine Liste für Multi-Auswahl), due. Mehrere zusammenhängende Fragen in einem Knoten werden zu einer Serie – ordnen Sie sie so, wie der Leser sie beantworten soll. Fragen Sie niemals nach Genehmigung für etwas bereits Getanes.
• aktionen – Dinge, die nur der Leser tun kann, mit dem genauen command und due, wenn relevant.
• geheimnisse – Der Bericht wird weitergeleitet. Der Build schlägt bei allem fehl, das wie ein Schlüssel, Token, privater Schlüssel, JWT, Passwortzuweisung oder Anmeldedaten in einer URL aussieht (gitleaks wird ebenfalls verwendet, wenn installiert). Entfernen Sie es aus dem Inhalt; „maskieren“ Sie es niemals von Hand. Geheimnisse in protokollierten Eingabeaufforderungen werden automatisch maskiert.

Struktur schreiben, keine Prosa

Jedes Textfeld rendert Struktur, geben Sie ihm also Struktur:

• - element → Aufzählungspunkte; 1. element → nummeriert (nur echte Sequenzen); zwei oder mehr Schlüssel: Wert-Zeilen → eine ausgerichtete Tabelle; ein JSON-Array von Zeichenfolgen → Aufzählungspunkte.
• **fett** für das eine oder zwei Dinge pro Zeile, die der Leser nicht übersehen darf; ==text== hebt hervor; `code` für Bezeichner, Pfade, Befehle.
• Kein Absatz länger als zwei Sätze; keine Untertitel oder Einleitungszeilen.

Feldhinweise: brief – 1–3 Schlüssel: Wert-Zeilen für die Kartenkarte. problem – Schlüssel/Wert-Fakten. goal – Aufzählungspunkte, was „erledigt“ bedeutet. result.summary – Schlüssel/Wert oder Aufzählungspunkte.

Sprache

Inhalt in der Sprache des Benutzers, meta.lang auf den entsprechenden Code gesetzt. Strukturbeschriftungen bleiben Englisch.

Dateien

• assets/template.html – die Struktur: Markup mit Platzhaltern, Stilen, Symbolen und einem Skript für Layout, Navigation, Suche, die Eingabeaufforderungsleiste und die Beantwortung.
• scripts/build.py – validiert den Inhalt (oben genannte Prüfungen, Geheimnisse), kennzeichnet das Journal, rendert die Vorlage. --check validiert nur; --template verwendet eine andere Vorlage.
• scripts/track.py – start, wait, hook, stop-hook, daemon, status, install-hook (siehe Docstring).
• scripts/statusline.py – der Berichtslink für die Claude Code-Statuszeile.
• references/schema.md – jedes Feld.
• examples/ – Englische und russische Beispiele; das russische trägt ein 5-Eingabeaufforderungs-Journal.