Skip to content

feat(portfolio): Belegstufen Ist/Soll/Meldung im Fakten-Index (D10a, v0.55.0) - #321

Merged
Jaegerfeld merged 1 commit into
mainfrom
feat/d10a-belegstufe
Nov 18, 2026
Merged

Jaegerfeld merged 1 commit into
mainfrom
feat/d10a-belegstufe

Conversation

@Jaegerfeld

Copy link
Copy Markdown
Owner

Was sich ändert

Roadmap D10, Schnitt a: Jeder Fakt des Fakten-Index trägt eine Belegstufe — Ist (actual, vom Werkzeug gemessen), Soll (target: Ziel, Termin, Schwelle, Beschluss) oder Meldung (reported: von einer Stelle eingetragen). Ein neuer Belegstufen-Wächter verwirft Antworten des befragbaren Lagebilds, die ein Soll oder einen gemeldeten Zustand als Zustand ausgeben. Unter jeder Antwort steht der vom Werkzeug gezählte Belegspiegel, zum Beispiel „Belege (vom Werkzeug gezählt): 1 Ist · 1 Soll · 5 Meldung".

Anlass ist ein Gesprächsverlauf mit einem KI-Assistenten vom 17.11.2026, der Zielwerte als Zustand behandelte und sein Urteil danach nach dem Widerspruch des Fragenden richtete. Konzept und Entscheidungen E1–E7 (Robert, 18.11.2026, „wie empfohlen") liegen lokal unter Ideen/.

Bausteine

  • portfolio/facts.py: Fact.basis, Zuordnung je Baustein, TARGET_FIELDS (due, needed_by, review_by, target_pct, threshold, horizon, follow_up_pi), Legende im Index; Wert und Status eines Entscheidungspunkts erben die Stufe der beobachteten Kennzahl. Faktenzeile: - [S1/total.median_ct] {actual} ….
  • llm/guard.py: basis_violations (Wortliste Deutsch und Englisch, kein zweites Modell), BasisGuardError (eine CitationGuardError, daher greifen GUI, CLI und Noise-Audit unverändert), basis_counts, basis_mirror (fünf Sprachen).
  • llm/prompts.py: Prompt-Version v3, Regel „Belegstufen" im Fragen-Prompt DE/EN.
  • portfolio/ask.py, portfolio/gui.py, llm/check.py: Wächter nach dem Zitat-Wächter, Belegspiegel im Dialog, in der .ask.md und im geprüften Entwurf des Rückwegs; neue Ablehnungsmeldung in fünf Sprachen. Bündel, die vor 0.55.0 exportiert wurden, tragen keine Stufen und werden wie bisher geprüft.

Abweichung vom Konzept — bitte bestätigen

Das Konzept verlangte ein Kennwort für jeden Satz, der nur Soll- oder Meldungs-Fakten zitiert. Beim Bau zeigte sich: Die geprüfte Musterantwort des Tutorials wäre daran in zwei von vier Sätzen gescheitert („Betroffen sind ART Alpha-1 als Geber und ART Alpha-3 als Nehmer"). Gebaut ist deshalb: Kennwortpflicht für jedes Soll und für Meldungen, die einen Zustand behaupten (Status, ROAM, Health, Bewertung, Zählung nach Status). Beschreibende Registerfelder zählen im Belegspiegel als Meldung, brauchen aber kein Kennwort. Wenn die strenge Fassung gewünscht ist, ist das eine Zeile in llm/guard.py.

UX read (vor dem ersten Edit an Dialog und Datei)

  • Nutzer und Ziel: Portfolio- oder Solution-Verantwortliche, die eine Frage an einen Stand gestellt haben und vor dem Verwenden wissen wollen, worauf die Antwort steht.
  • Primäre Aktion: die Antwort lesen und ihre Tragfähigkeit einschätzen.
  • Gesetze im Spiel:
    1. Law of Proximity: Der Belegspiegel steht direkt unter der Antwort, nicht in der Statuszeile.
    2. Selective Attention: Der Spiegel ist kein KI-Text; er trägt den Zusatz „vom Werkzeug gezählt" und steht hinter einer Trennlinie.
    3. Farbe nie als einziges Signal (WCAG 1.4.1; Stapelkamp, Web X.0, S. 84, 92): Stufen durch Wort und Zahl, keine Ampelfarben.
    4. Jakob's Law im Produkt: gleicher Wortlaut und gleiche Reihenfolge Ist · Soll · Meldung in Dialog, .ask.md und Rückweg; alle drei Stufen stehen immer da.
    5. Feedback, Meldungsklasse Fehler (Thesmann, S. 380 f.): Die neue Ablehnung sagt in der Sprache der Oberfläche, was passiert ist und was zu tun ist.
  • Standardfehler, die ich nicht baue: das Nur-Farbe-Signal, die anklagende Fehlermeldung, die Sackgasse.
  • Zustände: Antwort mit Spiegel; „keine Angabe" mit „keine zitierten Fakten"; verworfen wegen Belegstufe; exportiert ohne Spiegel.
  • Annahmen: Desktop, tkinter, Maus; Antwortsprache im Dialog Deutsch oder Englisch.

UX check

# Gesetz Ergebnis Wo
1 Law of Proximity Gehalten portfolio/gui.py:2017-2020, portfolio/ask.py:189-191
2 Selective Attention Gehalten: Kopf „Belege (vom Werkzeug gezählt)", Trennlinie im Dialog, Fettzeile in der Datei llm/guard.py:377-385, portfolio/gui.py:2020
3 Farbe nie einziges Signal Gehalten: reiner Text, keine Farbe llm/guard.py:440
4 Jakob's Law Gehalten: eine Funktion basis_mirror für Dialog, Datei und Rückweg; Dialog nutzt die Antwortsprache wie die Datei portfolio/ask.py:89-91, llm/check.py (checked_text)
5 Feedback Teilweise gehalten: Statuszeile in fünf Sprachen mit Handlungshinweis; die Einzelverstöße im Antwortfeld bleiben englisch wie bei den übrigen Wächtern portfolio/gui.py:262, :2021-2023

Based on Laws of UX by Jon Yablonski, lawsofux.com. Published by Pip Decks.

Texte zur Freigabe

  • CHANGELOG.md: Eintrag 0.55.0 (Added, Changed)
  • docs/modules/portfolio.de.md und portfolio.md: Abschnitt „Belegstufen: Ist, Soll, Meldung"
  • docs/modules/llm.de.md und llm.md: ein Satz zum Rückweg
  • docs/generate_portfolio_manual.py: Absatz in 5.19, fünf Sprachen (PDFs neu erzeugt)
  • docs/tutorials/ask-the-picture.de.md und .md: sechster Begriff, Spiegel im Beispiel, vierte Verstoßart; Zahlen auf den heutigen Demo-Stand gebracht (598 Fakten, Prompt v3)
  • docs/generate_feature_onepagers.py: Onepager „Belegstufen" DE/EN (evidence_basis)
  • docs/portfolio_roadmap_solution-lagebild.md: D10 mit Ist-Stand, Abweichung, offenen Schnitten

Prüfung

  • ruff sauber, mypy sauber
  • pytest gesamt: 2 057 bestanden, 1 abgewählt (ollama_live)
  • Musterantwort des Tutorials gegen den echten Demo-Index: Zitat- und Belegstufen-Wächter bestanden, Spiegel „1 Ist · 1 Soll · 5 Meldung"
  • Erzeugte PDFs (fünf Handbücher, zwei Tutorials, zwei Onepager) per pypdf-Textsuche geprüft
  • Kein echtes Sprachmodell im Test: wie streng der Wächter mit kleinen lokalen Modellen wirkt, zeigt erst der Einsatz

Danach

Schnitt b (Wertungswort- und Gefälligkeits-Wächter) und Schnitt c (Gegenprobe in drei Rahmungen). beta/ux-redesign holt main nach dem Merge nach. Merge, Tag und Release nur auf Roberts Wort.

🤖 Generated with Claude Code

…v0.55.0)

Jeder Fakt traegt eine Belegstufe (Fact.basis): actual (vom Werkzeug
gemessen), target (Ziel, Termin, Schwelle, Beschluss) oder reported (von
einer Stelle eingetragen). Die Contract-Zeile zeigt die Stufe, der Index
erklaert sie in einem Satz.

Neuer Belegstufen-Waechter (llm/guard.py::basis_violations): Zitiert ein
Satz keinen Ist-Fakt, sondern nur ein Soll oder eine Meldung, die einen
Zustand behauptet, und sagt das nicht, wird die Antwort verworfen
(BasisGuardError, eine CitationGuardError). Wortliste DE/EN, kein zweites
Modell. Unter jeder Antwort steht der vom Werkzeug gezaehlte Belegspiegel
("1 Ist . 1 Soll . 5 Meldung") - im Dialog, in der .ask.md und im
Rueckweg llm check. Prompt-Version v3.

Abweichung vom Konzept: Kennwortpflicht fuer Soll und zustandsbehauptende
Meldungen, nicht fuer jedes Registerfeld - die gepruefte Musterantwort des
Tutorials waere sonst gescheitert.

Tests: tests/llm/unit/test_basis_guard.py, Ergaenzungen in test_facts.py
und test_ask.py; Gesamtlauf 2057 bestanden, ruff und mypy sauber.
Doku: mkdocs portfolio/llm DE+EN, Manual 5.19 (fuenf Sprachen), Tutorial
DE+EN mit PDF, Onepager evidence_basis DE+EN, Roadmap D10, CHANGELOG.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@Jaegerfeld
Jaegerfeld merged commit 00de551 into main Nov 18, 2026
4 checks passed
@Jaegerfeld
Jaegerfeld deleted the feat/d10a-belegstufe branch November 18, 2026 13:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant