Alle Entscheidungen

Produkt- und technische Entscheidungen zu deciwa. Alle von Daniel entschieden; sie sind verbindliche Anforderungen an jedes Feature und jedes Stück Code. Geschäftliche Entscheidungen (Preise, Lizenz, Markt) liegen außerhalb dieses Repositorys.

Eine neue Entscheidung entsteht aus einem freigegebenen Vorschlag in den technischen Details – siehe An deciwa arbeiten.

ID	Title	Decided
DEC_PURPOSE	deciwa ist ein Review- und Entscheidungs-Tool für alle, die mit Docs und Code arbeiten	2026-10-17
DEC_NO_ENFORCING	deciwa sammelt, bewertet und zeigt; es überwacht nicht, ob Entscheidungen eingehalten werden	2026-10-17
DEC_VERDICTS	Feedback-Urteile plus Schnellaktionen für die KI	2026-10-17
DEC_FREEZE	Neues Urteil: einfrieren	2026-10-17
DEC_DECISION_IS_APPROVAL	Eine Entscheidung ist eine freigegebene Aussage, kein zusätzliches Objekt	2026-10-17
DEC_NO_MARKERS	Keine Markierungen im Quelltext; Elemente ergeben sich aus dem Inhalt	2026-10-17
DEC_FORMATS	Formate: Text, HTML, Python, C, JS, TS, rST, Markdown, AsciiDoc	2026-10-17
DEC_HOVER_SELECT	Format-Objekte werden beim Überfahren hervorgehoben und sind direkt auswählbar; freie Textauswahl bis hinunter zu einzelnen Wörtern	2026-10-17
DEC_REVIEW_ON_RESULTS	Reviews finden auf den Ergebnissen statt, nicht nur im Quelltext	2026-10-17
DEC_CLI_MASTER	Die CLI ist der Master, mit einem offen dokumentierten Dateiformat	2026-10-17
DEC_DECIWA_FOLDER	Alle deciwa-Dateien in einem Ordner .deciwa/ im Wurzelverzeichnis des Repositorys oder in einem übergeordneten Ordner	2026-10-17
DEC_GIT_COMMITTED	.deciwa/ wird standardmäßig in Git committet	2026-10-17
DEC_SKILLS	Ein oder zwei Agent-Skills für die Arbeit mit deciwa	2026-10-17
DEC_INTEGRATIONS	Integrationen: VS Code, Chrome, Claude-Oberfläche, Desktop-App	2026-10-17
DEC_FEEDBACK_CARD	Die Feedback-Karte am Element ist die Standard-Oberfläche; das Seitenpanel ist die Alternative; das Radialmenü ist verworfen	2026-10-17
DEC_DANWOS_TOKENS	deciwa nutzt die danwos-Farben und -Tokens	2026-10-17
DEC_THREE_MODES	Drei Arbeitsweisen, die getrennt bleiben: Feedback, Qualitätsbewertung, KI-Kommunikation	2026-10-18
DEC_CARD_VERDICTS	Die Feedback-Karte hat vier Urteile – freigeben, ablehnen, freigeben & einfrieren, löschen – plus einen Kommentar; ein Kommentar allein ist eine Notiz; Qualität wird mit 0–5 Sternen bewertet	2026-10-19
DEC_FREEZE_BY_VERDICT	Ein Einfrieren endet mit einem neuen Urteil; es gibt kein eigenes „Einfrieren aufheben“	2026-10-19
DEC_DOCS_IN_REPO	Entscheidungen, Features und Konzepte liegen im Repository als Sphinx-Docs mit Sphinx-Needs	2026-10-19
DEC_WEB_SCRIPT_FIRST	Das Web-Skript kommt als 0.2, vor VS Code	2026-10-20
DEC_WEB_ONE_LINE	Ein Script-Tag genügt – deciwa erscheint immer dort, wo es geladen wird	2026-10-20
DEC_WEB_HOSTING	Das Web-Skript wird mit der Doku unter deciwa.danwos.dev/js/<version>/ gehostet	2026-10-20
DEC_WEB_SOURCE	Seiten Quelldateien zuzuordnen ist optional; die Adresse ist der Fallback	2026-10-20
DEC_PACKAGES	deciwa ist ein Repository aus getrennten Paketen: Core, Server, CLI, UI und eines pro Integration	2026-10-20
DEC_REPLACES_CHECK	deciwa ersetzt die [CHECK]-Markierungen in Daniels Wissensbasis	2026-10-22
DEC_HOST_EXTENSIONS	Host-Apps bekommen deciwa als Erweiterung, die in diesem Repository liegt; der Host bietet nur allgemeine Erweiterungspunkte	2026-10-22
DEC_STANDALONE_ENGINE	Die Python-Teile lassen sich als eigenständiges Binary ausliefern, das Host-Apps mitbringen	2026-10-22
DEC_SERVE_API_ONLY	Ein Host spricht mit deciwa serve --api-only: die JSON-API für einen Ordner, ohne Build, mit Token und Handshake, endet mit dem Host	2026-10-22
DEC_HOST_ELEMENTS	In einem Host bekommt das Overlay seine Elemente vom Adapter der Engine, zugeordnet zu den Blöcken, die der Host mit ihrer Quellzeile markiert	2026-10-22
DEC_CLIENT_PACKAGE	Ein TypeScript-Client für alle Hosts findet, startet und prüft die Engine und ruft ihre API auf	2026-10-22
DEC_PYTHON_ADAPTER	Python-Quelltext wird je Klasse, Funktion, Methode und Anweisung außerhalb von Funktionen geprüft, gelesen mit ast aus der Standardbibliothek	2026-10-22
DEC_HTML_ADAPTER	HTML-Dateien liest ein Adapter in der Engine, mit Quellzeilen; die dargestellte Seite und die Quelltextansicht teilen sich seine Elemente	2026-10-22
DEC_FACT_BLOCKS	Ein Fakt ist ein Block einer Faktendatei – ein Listenpunkt, eine Tabellenzeile oder ein freier Absatz –, keine im Text gefundene Bedeutung	2026-10-22
DEC_DATA_ADAPTERS	JSON- und YAML-Dateien werden Wert für Wert reviewt; Selektoren sind JSON Pointer	2026-10-22
DEC_HOST_ORDER	monsterbrain ist der erste Host, vor VS Code	2026-10-22

Zweck und Umfang

Entscheidung: deciwa ist ein Review- und Entscheidungs-Tool für alle, die mit Docs und Code arbeiten DEC_PURPOSE

status: approved decided: 2026-10-17 reason: Daniel braucht einen einfachen Weg, Inhalte zu reviewen und Aussagen zuzustimmen (Auslöser: seine eigene Arbeit in seiner Wissensbasis). alternatives: nur ein Entscheidungslog; ein Tool für eine einzige Gruppe (Entwicklung, KI-Agenten oder Management).

Entscheidung: deciwa sammelt, bewertet und zeigt; es überwacht nicht, ob Entscheidungen eingehalten werden DEC_NO_ENFORCING

status: approved decided: 2026-10-17 reason: Entscheidungen durchzusetzen ist nicht möglich; die Arbeit selbst ist Aufgabe der KI oder der Entwicklung. alternatives: ein „Watcher“, der die Umsetzung prüft (verworfen). refined by: PROP_CLI_CHECK

Entscheidung: Drei Arbeitsweisen, die getrennt bleiben: Feedback, Qualitätsbewertung, KI-Kommunikation DEC_THREE_MODES

status: approved decided: 2026-10-18 reason: Sterne sind eine schnelle Einschätzung unabhängig von jedem Urteil, um sich später auf schwache Stellen zu konzentrieren; Fragen der KI werden am Element per Urteil oder Text beantwortet. alternatives: Sterne als Teil eines Urteils. refined by: PROP_ANNOTATION, PROP_LATEST_WINS, PROP_STATE_RULES

Feedback und Entscheidungen

Entscheidung: Die Feedback-Karte hat vier Urteile – freigeben, ablehnen, freigeben & einfrieren, löschen – plus einen Kommentar; ein Kommentar allein ist eine Notiz; Qualität wird mit 0–5 Sternen bewertet DEC_CARD_VERDICTS

status: approved decided: 2026-10-19 reason: Im Prototyp gesehen: sieben dreizeilige Buttons waren zu groß; was sich an einem Text ändern soll, sagt der Kommentar besser als Buttons für Umformulieren oder Mehr Details; eine Notiz ist einfach ein Kommentar ohne Urteil; Qualität braucht eine klare Skala mit Tasten. alternatives: die sieben Buttons des klickbaren Prototyps (freigeben, umformulieren, mehr Details, löschen, einfrieren, ablehnen, Notiz) und 1–5 Sterne. refined by: Q_QUICK_ACTIONS

Entscheidung: Ein Einfrieren endet mit einem neuen Urteil; es gibt kein eigenes „Einfrieren aufheben“ DEC_FREEZE_BY_VERDICT

status: approved decided: 2026-10-19 reason: Ein erneutes Freigeben ersetzt das eigene Einfrieren ohnehin (solange das Element unverändert ist, gilt das neueste Urteil); ein zweiter Weg, es aufzuheben, verwirrt nur. alternatives: ein ausdrücklicher Befehl zum Auftauen nur für Menschen; das Löschen der Einfrier-Annotation.

Entscheidung: Feedback-Urteile plus Schnellaktionen für die KI DEC_VERDICTS

status: approved decided: 2026-10-17 reason: Freigeben, ablehnen, Notiz und die Schnellaktionen umformulieren, mehr Details und löschen geben der KI mit einem Klick eine vollständige Anweisung. alternatives: nur freie Kommentare. refined by: PROP_ANNOTATION

Entscheidung: Neues Urteil: einfrieren DEC_FREEZE

status: approved decided: 2026-10-17 reason: Manche Formulierungen müssen jede Bearbeitung überstehen; die KI darf sie nie ändern, und deciwa schlägt Alarm, wenn sie sich trotzdem ändern. alternatives: – refined by: PROP_ANNOTATION, PROP_CLI_CHECK, PROP_STATE_RULES

Entscheidung: Eine Entscheidung ist eine freigegebene Aussage, kein zusätzliches Objekt DEC_DECISION_IS_APPROVAL

status: approved decided: 2026-10-17 reason: Entscheidungen lassen sich dann auf alles abbilden, was ein Element ist. alternatives: eigene Entscheidungsdatensätze im Quelltext. refined by: PROP_STATE_RULES

Elemente und Formate

Entscheidung: Keine Markierungen im Quelltext; Elemente ergeben sich aus dem Inhalt DEC_NO_MARKERS

status: approved decided: 2026-10-17 reason: Der Quelltext bleibt sauber, und jedes Element bleibt dokumentiert (eine Sphinx-Needs-Anforderung, eine Überschrift, eine Python-Funktion, ein HTML-Container, ein markiertes Wort). alternatives: Markierungen im Stil von [CHECK] oder IDs im Text. refined by: PROP_ADAPTER_API, PROP_RESOLVE, PROP_ROLLOUT_MIGRATE

Entscheidung: deciwa ersetzt die [CHECK]-Markierungen in Daniels Wissensbasis DEC_REPLACES_CHECK

status: approved decided: 2026-10-22 reason: Eine Frage am Element mit Adressat und Zustand ersetzt eine Markierung im Text ({need}`DEC_NO_MARKERS`); offene Fragen erscheinen in jeder Integration, statt mit `rg` gesucht zu werden. alternatives: `[CHECK]` neben deciwa beibehalten.

Entscheidung: Formate: Text, HTML, Python, C, JS, TS, rST, Markdown, AsciiDoc DEC_FORMATS

status: approved decided: 2026-10-17 reason: Docs-as-Code plus die Ergebnisse und der Code drumherum. alternatives: nur Markdown. refined by: PROP_PYTHON_CORE

Entscheidung: Format-Objekte werden beim Überfahren hervorgehoben und sind direkt auswählbar; freie Textauswahl bis hinunter zu einzelnen Wörtern DEC_HOVER_SELECT

status: approved decided: 2026-10-17 reason: Zeigen muss so schnell gehen wie Hinsehen. alternatives: zeilenbasierte Auswahl wie in einem Code-Review. refined by: PROP_ADAPTER_API, PROP_FREE_TEXT

Entscheidung: Reviews finden auf den Ergebnissen statt, nicht nur im Quelltext DEC_REVIEW_ON_RESULTS

status: approved decided: 2026-10-17 reason: Gerenderte Docs und Websites sind das, was Reviewende sehen; deciwa darf nicht wie ein Pull-Request-Code-Review aussehen. Die Quelltextansicht zeigt dasselbe Element. alternatives: Review nur im Quelltext. refined by: PROP_PYTHON_CORE

Architektur und Daten

Entscheidung: Die CLI ist der Master, mit einem offen dokumentierten Dateiformat DEC_CLI_MASTER

status: approved decided: 2026-10-17 reason: Eine Logik für alle Frontends; Agenten und Integrationen nutzen dieselben Befehle und dasselbe JSON. alternatives: eine Web-App als Kern. refined by: PROP_CLI_COMMANDS, PROP_CLI_JSON, PROP_LAYERS, PROP_OVERLAY_PARTS, PROP_PYTHON_CORE, PROP_SCHEMA

Entscheidung: Alle deciwa-Dateien in einem Ordner .deciwa/ im Wurzelverzeichnis des Repositorys oder in einem übergeordneten Ordner DEC_DECIWA_FOLDER

status: approved decided: 2026-10-17 reason: Die Dateien dürfen nicht im Weg sein; ein übergeordneter Ordner deckt mehrere Repositorys ab oder Repositorys, die unberührt bleiben müssen. alternatives: Sidecar-Dateien neben jeder Quelle. refined by: PROP_FILE_LAYOUT, PROP_ROLLOUT_LOCATION, PROP_WEB_SOURCE

Entscheidung: .deciwa/ wird standardmäßig in Git committet DEC_GIT_COMMITTED

status: approved decided: 2026-10-17 reason: Reviews werden zusammen mit dem Inhalt versioniert. alternatives: von Git ignoriert, bis ein Team entscheidet. refined by: PROP_FILE_LAYOUT, PROP_ROLLOUT_LOCATION

Entscheidung: Ein oder zwei Agent-Skills für die Arbeit mit deciwa DEC_SKILLS

status: approved decided: 2026-10-17 reason: Agenten sollen Feedback aufgreifen und Fragen stellen, ohne extra dazu aufgefordert zu werden (deciwa-work, deciwa-ask). alternatives: – refined by: PROP_SKILLS_FORMAT

Entscheidung: Host-Apps bekommen deciwa als Erweiterung, die in diesem Repository liegt; der Host bietet nur allgemeine Erweiterungspunkte DEC_HOST_EXTENSIONS

status: approved decided: 2026-10-22 reason: deciwa wird nur hier entwickelt; ein Host wie monsterbrain oder VS Code darf keine Kopie von deciwa-Code enthalten. Dieselbe Server-API und dasselbe Overlay bedienen jeden Host, nur ein dünner Adapter unterscheidet sich. alternatives: das Overlay und eine Portierung der Engine in den Host kopieren; eine fest in den Host eingebaute deciwa-Integration.

Entscheidung: Die Python-Teile lassen sich als eigenständiges Binary ausliefern, das Host-Apps mitbringen DEC_STANDALONE_ENGINE

status: approved decided: 2026-10-22 reason: monsterbrain wird verteilt, und die VS-Code-Erweiterung muss ohne Python auf dem Rechner laufen; Nutzer installieren eine App, keine Python-Umgebung. alternatives: Python und `uv tool install deciwa` als Voraussetzung für jeden Host; eine Portierung des Kerns nach TypeScript. refined by: PROP_ENGINE_BINARY

Entscheidung: Ein Host spricht mit deciwa serve --api-only: die JSON-API für einen Ordner, ohne Build, mit Token und Handshake, endet mit dem Host DEC_SERVE_API_ONLY

status: approved decided: 2026-10-22 reason: Ein Host stellt die Inhalte selbst dar und braucht nur die Logik der Engine; Port 0 und ein Token halten mehrere Hosts und andere lokale Seiten auseinander; ein geschlossenes stdin beendet die Engine, sie läuft also nie länger als ihr Host. alternatives: das volle `deciwa serve` mit gebauter Website; die Engine als Python-Bibliothek im Host.

Entscheidung: In einem Host bekommt das Overlay seine Elemente vom Adapter der Engine, zugeordnet zu den Blöcken, die der Host mit ihrer Quellzeile markiert DEC_HOST_ELEMENTS

status: approved decided: 2026-10-22 reason: Der Host stellt dar, der Adapter kennt die Elemente – Feedback bekommt dieselben Selektoren wie in der CLI, so zeigt `deciwa todo` auf die Quellzeile. Dargestellte HTML-Dateien behalten den DOM-Scan mit dem Dateipfad als Quelle. alternatives: ein DOM-Scan der Darstellung des Hosts (andere Selektoren als in der CLI); der Host schickt eine eigene Elementliste.

Entscheidung: Ein TypeScript-Client für alle Hosts findet, startet und prüft die Engine und ruft ihre API auf DEC_CLIENT_PACKAGE

status: approved decided: 2026-10-22 reason: monsterbrain und VS Code brauchen denselben Umgang mit der Engine; nur der Adapter, der die Ergebnisse in die Oberfläche des Hosts bringt, ist verschieden. alternatives: jeder Host-Adapter spricht selbst mit der Engine.

Entscheidung: Python-Quelltext wird je Klasse, Funktion, Methode und Anweisung außerhalb von Funktionen geprüft, gelesen mit ast aus der Standardbibliothek DEC_PYTHON_ADAPTER

status: approved decided: 2026-10-22 reason: Code-Repositories werden in monsterbrain neben der Wissensbasis geprüft; ast liefert genaue Zeilenbereiche ohne neue Abhängigkeit. Der Python-Adapter rückt aus 0.4 vor; JS, TS und C folgen mit tree-sitter. alternatives: tree-sitter für alle Sprachen auf einmal (mehr Abhängigkeiten, eine größere eigenständige Engine); Review nur einzelner Zeilen.

Entscheidung: HTML-Dateien liest ein Adapter in der Engine, mit Quellzeilen; die dargestellte Seite und die Quelltextansicht teilen sich seine Elemente DEC_HTML_ADAPTER

status: approved decided: 2026-10-22 reason: HTML-Ergebnisse in einer Wissensbasis werden als Seite und als Code geprüft; mit Quellzeilen aus der Engine zeigt Feedback auf der Seite auf den Quelltext, und `deciwa todo` nennt die Zeile. Er folgt den Regeln des DOM-Scans im Browser, die Selektoren bleiben also gleich. alternatives: nur der DOM-Scan der dargestellten Seite (keine Quellzeilen, kein Review des Codes).

Entscheidung: Ein Fakt ist ein Block einer Faktendatei – ein Listenpunkt, eine Tabellenzeile oder ein freier Absatz –, keine im Text gefundene Bedeutung DEC_FACT_BLOCKS

status: approved decided: 2026-10-22 reason: Selektoren und Fingerprints des Markdown-Adapters machen jeden Block ohne Markup reviewbar, bei jedem Lauf gleich; eine KI, die Fakten nach Bedeutung findet, schneidet jedes Mal anders, und Freigaben verlieren ihren Anker. Das Brain ist bereits in Listen und Tabellen geschrieben, mit einem Fakt pro Listenpunkt als Schreibregel. Eine Faktendatei kann auch als Ganzes freigegeben werden; diese Freigabe veraltet bei jeder Änderung der Datei, die Freigaben ihrer Fakten bleiben je Fakt. alternatives: ein ganzer Abschnitt als ein Fakt (weniger, gröbere Freigaben); ausdrückliches Markup mit einer Id je Fakt; Fakten, die eine KI herauszieht.

Entscheidung: JSON- und YAML-Dateien werden Wert für Wert reviewt; Selektoren sind JSON Pointer DEC_DATA_ADAPTERS

status: approved decided: 2026-10-22 reason: Datendateien – Design-Tokens, Konfigurationen, `needs.json`, Exporte – sind auch Ergebnisse. Jeder Wert ist ein Element, Blätter eingeschlossen: das Dokument, jedes Objekt-Mitglied und jeder Array-Eintrag. Selektoren sind JSON Pointer (RFC 6901) mit dem Index für Array-Einträge; es gibt keine Regeln, die von den Daten abhängen (keine Id-Felder, keine Sonderansichten für bekannte Dateien). Ein Eintrag, der sich verschiebt, weil davor etwas eingefügt wird, behält sein Review, weil die Engine verschobenen Elementen folgt – in jedem Format. Nur Standard-JSON (kein JSON Lines, kein JSONC) und das erste Dokument einer YAML-Datei. alternatives: Id-Felder als Namen für Array-Einträge (datenabhängig); Sonderansichten für `needs.json` oder Tokens; Review nur nach Zeilen.

Entscheidung: monsterbrain ist der erste Host, vor VS Code DEC_HOST_ORDER

status: approved decided: 2026-10-22 reason: Daniel nutzt monsterbrain täglich für seine Wissensbasis, den ersten Einsatz von deciwa; es erprobt den API-Server, die Host-Elementquelle und den Client, die VS Code später braucht. alternatives: VS Code zuerst.

Oberfläche und Integrationen

Entscheidung: Integrationen: VS Code, Chrome, Claude-Oberfläche, Desktop-App DEC_INTEGRATIONS

status: approved decided: 2026-10-17 reason: Reviews finden dort statt, wo man ohnehin arbeitet – Editor, Browser, Chat; die Desktop-App deckt alle ohne IDE ab. alternatives: – refined by: PROP_WEB_ONE_LINE

Entscheidung: Die Feedback-Karte am Element ist die Standard-Oberfläche; das Seitenpanel ist die Alternative; das Radialmenü ist verworfen DEC_FEEDBACK_CARD

status: approved decided: 2026-10-17 reason: Im klickbaren Prototyp verglichen. alternatives: ein Radialmenü am Cursor.

Entscheidung: deciwa nutzt die danwos-Farben und -Tokens DEC_DANWOS_TOKENS

status: approved decided: 2026-10-17 reason: Wiedererkennung über alle danwos-Tools hinweg; die Farben des deciwa-Monsters sind nur für Bilder. alternatives: ein eigenes deciwa-Farbschema.

Entscheidung: Das Web-Skript kommt als 0.2, vor VS Code DEC_WEB_SCRIPT_FIRST

status: approved decided: 2026-10-20 reason: Der erste echte Einsatz ist die danwos-Website; die Chrome-Erweiterung baut auf demselben Skript auf. alternatives: das Web-Skript als Teil der Chrome-Erweiterung in 0.3.

Entscheidung: Ein Script-Tag genügt – deciwa erscheint immer dort, wo es geladen wird DEC_WEB_ONE_LINE

status: approved decided: 2026-10-20 reason: Schnelle Einbindung und Tests ohne Vorwissen; jede Einstellung ist optional, deciwa hinter `?deciwa` zu verstecken ist ein Opt-in. alternatives: `?deciwa` in der Adresse als einziger Weg, es zu laden.

Entscheidung: Das Web-Skript wird mit der Doku unter deciwa.danwos.dev/js/<version>/ gehostet DEC_WEB_HOSTING

status: approved decided: 2026-10-20 reason: Der Docs-Workflow veröffentlicht deciwa.danwos.dev bereits; versionierte Pfade erlauben Pinning. alternatives: npm mit jsDelivr.

Entscheidung: Seiten Quelldateien zuzuordnen ist optional; die Adresse ist der Fallback DEC_WEB_SOURCE

status: approved decided: 2026-10-20 reason: deciwa muss ohne Konfigurationsdatei funktionieren; eine später ergänzte Zuordnung darf kein Feedback verlieren. alternatives: ein Pflicht-Meta-Tag `deciwa-source` auf jeder Seite.

An deciwa arbeiten

Entscheidung: deciwa ist ein Repository aus getrennten Paketen: Core, Server, CLI, UI und eines pro Integration DEC_PACKAGES

status: approved decided: 2026-10-20 reason: CLI und Server werden von jeder Integration wiederverwendet; die Logik bleibt an einer Stelle (Core); Integrationen wie Sphinx, VS Code oder Chrome bleiben voneinander unabhängig. alternatives: ein Paket mit allem (der erste Prototyp, deciwa_proto). refined by: PROP_LAYERS

Entscheidung: Entscheidungen, Features und Konzepte liegen im Repository als Sphinx-Docs mit Sphinx-Needs DEC_DOCS_IN_REPO

status: approved decided: 2026-10-19 reason: Andere entwickeln auch im Repository, und Entscheidungen wirken als Anforderungen; Sphinx-Needs gibt jeder Entscheidung eine ID, einen Status und Links, und deciwa kann später seine eigenen Docs reviewen. alternatives: Entscheidungen nur in Daniels Wissensbasis; MkDocs Material (reiner Text ohne IDs oder Rückverfolgbarkeit). refined by: PROP_DOCS_TRANSLATION