Bra1nZ/evidence-first-docs

Evidence-First Docs (Evidenzbasierte Dokumentation)

Dokumentation ist keine Geschichte über das System. Sie ist ein Anspruchsregister: Jede materielle Aussage muss rückverfolgbar sein zu einem Mechanismus und zu Belegen, wobei die Grenzen an derselben Stelle wie die Behauptung angegeben werden.

Ein selbstbewusster Satz ist billig. Die Aufgabe besteht darin, den Leser in die Lage zu versetzen, zu erkennen, was bewiesen, was getestet, was nur überprüft wurde und was noch offen ist.

Die Kernregel

Jede materielle Behauptung trägt vier Dinge:

1. Mechanismus — was im System die Behauptung wahr machen soll.
2. Beleg — das Beweisartefakt: Beweis, Modell, Test, Analysebericht, Trace, Benchmark oder Überprüfungsprotokoll.
3. Umfang — wo die Behauptung gilt und was außerhalb der Vertrauensgrenze liegt.
4. Status — die stärkste ehrliche Bezeichnung, die der Beleg unterstützt.

Fehlt eines der vier, ist die Behauptung nicht fertig. Formulieren Sie sie um als Designintention, einen Plan oder eine offene Frage — kleiden Sie sie nicht als Ergebnis ein.

Anspruchsregister

Führen Sie eine Tabelle, entweder im Dokument oder in einer verlinkten Belegdatei:

ID	Behauptung	Mechanismus	Beleg	Umfang / TCB	Status	Einschränkungen	Zuletzt verifiziert
C-01	Nur Rolle X kann Tabelle T beschreiben	Berechtigungsprüfung + DB-Richtlinie	Negative Tests T-04..T-11	PostgreSQL 14–17; Rolle Y, rollenlose Sitzung	getestet	Superuser und DBA liegen außerhalb des Bedrohungsmodells	2026-11-02

Regeln:

• Eine Zeile pro Behauptung, nicht eine Zeile pro Dokument.
• Behauptungen müssen falsifizierbar sein. "Das System ist sicher" ist keine Behauptung; "Rolle Y kann T über keinen unterstützten Einstiegspunkt beschreiben" schon.
• Verlinken Sie das Artefakt, nicht nur den Tool-Namen. "SARIF" ist ein Format; der Berichtspfad und der überprüfte Regelsatz sind Belege.
• Aktualisieren Sie Zuletzt verifiziert, wenn das Artefakt erneut ausgeführt wird; veraltete Belege sind ein Befund, keine Formalität.
• Behalten Sie negative Ergebnisse bei. "Wir haben versucht, es zu brechen, und sind wegen X gescheitert" ist ein Beleg; das Verstecken erzeugt ein falsches Gefühl der Abdeckung.

Statusleiter

Verwenden Sie die stärkste Bezeichnung, die der Beleg unterstützt, niemals eine stärkere:

Status	Bedeutung
proven	Maschinengeprüfter Beweis der genannten Eigenschaft mit deklarierten Annahmen und TCB
model-checked	Vollständige oder beschränkte Exploration eines Modells; geben Sie die Schranke und die Modell-Code-Lücke an
tested	Ausgeführte Tests, die den Verstoß versuchen, mit aufgezeichneter Umgebung und Ergebnis
static-refinement	Statische Analyse oder Verfeinerungsprüfung; geben Sie Tool, Regeln und ungelöste Befunde an
reviewed	Nur menschliche Überprüfung; keine ausführbaren oder formalen Belege
open	Behauptung existiert, aber Belege nicht; es ist ein Risiko, kein Ergebnis

Ein niedrigerer Status ist kein Fehler. Ein überhöhter Status ist einer.

Schreiben Sie nicht verified, proven, correct, secure, safe, complete, guaranteed, certified oder compliant ohne einen benachbarten Status und Umfang. Wenn das Wort ohne den Beleg überleben würde, löschen Sie das Wort.

Belegstärke

Bevorzugen Sie Belege, die aus dem richtigen Grund scheitern können:

1. Formaler Beweis der genannten Eigenschaft unter expliziten Annahmen.
2. Vollständige Modellprüfung innerhalb einer angegebenen Schranke.
3. Eigenschaftsbasierte oder Fuzz-Tests mit aufgezeichnetem Korpus und Orakel.
4. Gezielte negative Tests, die fehlschlagen, wenn der Mechanismus entfernt wird.
5. Statische Analyse mit überprüftem Regelsatz und triagierten Befunden.
6. Code-Review mit benannten Prüfern und einer Checkliste.
7. Behauptung oder Anekdote.

Die Hierarchie ist nicht absolut: Ein gezielter Test kann stärker sein als ein falsch angewendeter Beweis. Passen Sie den Beleg an die Behauptung an. Ein Beweis eines Modells, das den Code nicht verfeinert, beweist nicht den Code. Ein Test, der besteht, weil die Plattform zuerst verweigert hat, beweist nicht Ihre Absicherung.

Umfang und Vertrauensgrenze

Geben Sie die Grenze neben der Behauptung an, nicht in einem fernen Anhang:

• Abgedeckte Versionen und Plattformen.
• Ausgeschlossene privilegierte Akteure: Superuser, DBA, Bereitstellungsadministrator, Secret Manager, Build-System, Operator.
• Annahmen: kryptografische Primitive, Uhr, Netzwerk, Speicher, Mandantenisolierung, Konfiguration.
• Was symbolisch modelliert und was tatsächlich ausgeführt wird.
• Was außerhalb des Rahmens liegt und warum.

Eine uneingeschränkte Behauptung ist eine Behauptung über alles, was fast immer falsch ist. "Sicher gegen Rolle Y auf PostgreSQL 14–17 mit der dokumentierten Konfiguration; DBA liegt außerhalb des Modells" ist ehrlich und nützlich.

Arbeitsablauf

1. Ansprüche inventarisieren. Lesen Sie den Text und markieren Sie jeden Satz, der eine Eigenschaft, ein Ergebnis, eine Garantie oder einen Compliance-Status behauptet.
2. Jeden Anspruch klassifizieren. Handelt es sich um eine Designintention, eine Anforderung, eine Implementierungstatsache, ein Testergebnis, ein formales Ergebnis oder eine Release-Behauptung?
3. Eine ID und einen Status vergeben. Fügen Sie Mechanismus, Beleg, Umfang, Einschränkungen und Zuletzt verifiziert hinzu.
4. Den Anspruch gegen das Artefakt testen. Öffnen Sie den Bericht, führen Sie den Befehl erneut aus oder fragen Sie nach dem fehlenden Artefakt. Akzeptieren Sie keinen Dateinamen als Beleg.
5. Nicht unterstützte Ansprüche umschreiben. Wandeln Sie sie in "Designintention", "geplant", "noch nicht verifiziert" oder eine offene Frage um. Bewahren Sie den Ehrgeiz; entfernen Sie die falsche Sicherheit.
6. Die Negativfälle prüfen. Nennen Sie für jede Sicherheits- oder Korrektheitsbehauptung den Test oder die Analyse, die versucht hat, sie zu verletzen. Wenn es keine gibt, markieren Sie die Behauptung als open.
7. Die Sprache überprüfen. Entfernen Sie verbotene Wörter, vage Quantifizierer und uneingeschränkte Absolutheiten. Siehe references/banned-words.md.
8. Die Belege einfrieren. Zeichnen Sie Befehl, Commit, Umgebung, Datum und Artefaktpfad auf, damit ein Prüfer das Ergebnis reproduzieren kann.
9. Die Veröffentlichung absichern. Ein Release Note darf nur das behaupten, was das Register unterstützt. Führen Sie Restrisiken und offene Ansprüche explizit auf.

Überprüfungscheckliste

• Jede materielle Behauptung hat eine ID, einen Mechanismus, einen Beleg, einen Umfang, einen Status und Einschränkungen.
• Jede tested-Behauptung nennt einen Test, der fehlschlagen kann, wenn der Mechanismus entfernt wird.
• Jede model-checked-Behauptung gibt die Schranke und die Modell-Code-Lücke an.
• Jede proven-Behauptung gibt Annahmen und TCB an.
• Negative Ergebnisse und bekannte Fehlschläge sind vorhanden, nicht herausgefiltert.
• Daten und Versionen sind aktuell; veraltete Belege sind als veraltet markiert.
• Privilegierte Akteure und ausgeschlossene Pfade sind benannt.
• Kein verbotenes Wort erscheint ohne angrenzenden Beleg und Umfang.
• Die README, das Architekturdokument, der API-Vertrag und der Release Note widersprechen sich nicht.
• Ein Leser kann die Belege allein aus dem Dokument reproduzieren.

Anti-Patterns

1. Zukunftsorientiertes Präsens. "Das System erzwingt..." wenn es ein Plan ist.
2. Beleg durch Dateinamen. "Siehe report.pdf" ohne Ergebnis, Umfang oder Datum.
3. Tool-Name als Beweis. "Verifiziert mit statischer Analyse" ohne Regeln, Befunde und Triage.
4. Umfangswäsche. Ein enges Testergebnis als produktweite Garantie präsentiert.
5. Grünes-Suite-Absolutismus. "Alle Tests bestanden" ohne zu sagen, welche Tests, auf welchen Plattformen und was sie zu verletzen versuchten.
6. Compliance-Kosmetik. Der Name eines Standards als Zertifikat verwendet; eine Zuordnung ist kein Audit.
7. Vergrabene Einschränkungen. Der Vorbehalt existiert, ist aber weit von der Behauptung entfernt.
8. Veraltete Sicherheit. Ein Ergebnis aus einem alten Commit als aktuell präsentiert.
9. Keine negativen Belege. Nur Erfolge werden dokumentiert; Fehlschläge und Verweigerungen verschwinden.

Ausgabeform

Wenn Sie aufgefordert werden, ein technisches Dokument zu schreiben oder zu überprüfen, erstellen Sie:

1. Eine kurze Anspruchszusammenfassung mit Zählungen nach Status.
2. Das Anspruchsregister (inline oder verlinkt).
3. Offene Ansprüche und Restrisiko, explizit von Ergebnissen getrennt.
4. Umfang und Annahmen, neben den Ansprüchen, die sie einschränken.
5. Belegindex mit Pfaden, Befehlen, Daten und Versionen.

Verwenden Sie references/evidence-template.md für die Register- und Release-Notiz-Form. Verwenden Sie references/banned-words.md vor der Veröffentlichung. Wenn das Repository eine Standards-Kreuzreferenz enthält, befindet sie sich unter references/standards-map.md; das Skill selbst hängt nicht von einem Standard ab.

Passen Sie die Ausgabe an das Dokument an. Ein kurzer Release Note benötigt eine kompakte Anspruchstabelle und einen kurzen Abschnitt zum Restrisiko, kein vollständiges Audit-Paket. Eine Zertifizierungsbelegdatei benötigt das vollständige Register, den Belegindex und den Umfang. Verwechseln Sie nicht Gründlichkeit mit Länge; jede Zeile muss Informationen enthalten, die ein Leser benötigt.