diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 9278f74..03131c9 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -19,6 +19,7 @@ reverse. ## 2026-08-27 +- A benefit rating per node recorded as planned: a 0-9 digit inside the size token (`M/9`), and a third path mode that picks alternatives by benefit over cost — spelled out in SPEC §11 before it is built - A people bar below the diagram shows each `@person` with their share of the open work on the cheapest path — plus an entry for what is assigned to nobody - Tapping a person filters the diagram to their nodes: everything else folds, their packages stand collapsed as `▸ n`, their pills turn teal — a view-only lens that never writes into the text - Folding regions in the text editor recorded as an idea in the plan — view-only and local, unrelated to the diagram's fold marks, deliberately not sized yet diff --git a/docs/SPEC.md b/docs/SPEC.md index 6804581..31d0ed5 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -1299,6 +1299,40 @@ ist die frühere Dreifach-Rolle von `#` aufgelöst (D34). Extra-Syntax — gebaut werden sie erst **zusammen mit** dem ersten solchen Konsumenten. Bis dahin gilt allein: `&` nicht anderweitig vergeben. +### Nutzen je Knoten (`(M/9)`) — festgelegt, noch nicht gebaut + +Eine **unabhängige Nutzenbewertung** neben der Aufwandsschätzung; die +Abwägung geschieht erst bei der Priorisierung (lohnendster Pfad, unten). + +- **Notiert im Größen-Token:** `(Aufwand/Nutzen)`, z. B. `(M/9)`; nur Nutzen + `(/7)`; nur Größe wie bisher `(M)`. Es bleibt **ein** Token in **einer** + Ecke — Erkennungsregeln wie bei der Größe (§1, Schritt 4): alleinstehend + angesetzt, das **letzte** Token gewinnt, die Zitier-Konventionen gelten + (`"(M/9)"` bleibt Label). Ein ungültiger Nutzen (`(M/12)`, `(M/x)`) macht + das Token zum Label — der laute Fehlermodus (D59). +- **Skala: eine Ziffer 0–9.** `9` = hoher Nutzen, `1` = geringer, **`0` = + Vorbedingung**: muss gemacht werden, hat aber keinen eigenen Nutzen. Im + lohnendsten Pfad gewinnt eine `0` nie eine Alternativen-Wahl, wird aber + über Abhängigkeiten (`:#…`) und all-of-Notwendigkeit gezogen — genau die + Vorbedingungs-Semantik. +- **Reine Autoren-Aussage:** keine Aggregation über Teilbäume, keine + Konfliktprüfung, keine Schätzung fehlender Werte. Nutzen ist — anders als + Kosten — **nicht additiv**: Teilpakete können denselben Nutzen doppelt + versprechen (Überlappung) oder zusammen mehr sein (Synergie); es gibt + keine sichere Lesart, unter der eine Kindersumme den Elternwert widerlegt. + Größen-Konflikt (§5/D62) und Größen-Schätzung (D66) bleiben Kosten-Sache. +- **Anzeige** im vorhandenen Größen-Badge oben rechts (`M/9` bzw. `/7`); + die Knoten-Ecken bleiben, wie sie sind. +- **Lohnendster Pfad:** Der Pfad-Umschalter wird ein **Durchschalter mit + drei Stellungen** (aus → günstigster → lohnendster). Im lohnendsten Pfad + wählt eine Alternativgruppe nach **Nutzen/Kosten-Verhältnis**; + **Bewertetes schlägt Unbewertetes** (fehlender Nutzen zählt 0, sobald + mindestens eine Alternative der Gruppe bewertet ist), eine Gruppe ganz + ohne Bewertungen wählt nach Kosten wie bisher — ohne Nutzen-Angaben im + Dokument ist der lohnendste Pfad damit der günstigste. Realisiert bleibt + realisiert (D46/D61), Verworfenes zählt nie; Linie, Stationen und + Inversion behalten ihre Mechanik. + ### Abhängigkeiten zwischen Knoten (`:#auth,#api`) Die **Schreibweise ist umgesetzt** — Definition jetzt in §1 (Token-Vertrag, diff --git a/docs/examples/werkbaum.werkbaum b/docs/examples/werkbaum.werkbaum index d7c7e8c..d05ecaa 100644 --- a/docs/examples/werkbaum.werkbaum +++ b/docs/examples/werkbaum.werkbaum @@ -28,9 +28,9 @@ - [ ] #not.ticket: Ticket references (#123,#US-123) (S) %% Taiga writes #US-123 for a user story - [^] #not.llms: llms.md, the notation explained to AI agents (S) - [^] #not.llms.index: llms.txt, the signpost that points at it (XS) %% the convention wants an index, not the content - - [?] #not.benefit: Benefit per node, not only cost (M) - | [?] #not.benefit.sigil: Another sigil next to the size (S) - | [?] #not.benefit.points: Story points behind the T-shirt sizes (M) + - [ ] #not.benefit: Benefit per node: a 0-9 digit in the size token (M) %% (M/9), benefit alone as (/7) — see SPEC §11 + - [-] #not.benefit.sigil: A separate sigil next to the size (S) %% one token in one corner won + - [-] #not.benefit.points: Story points behind the T-shirt sizes (M) %% false precision — the sizes stay ordinal - [~] #ed: Editor (XXL) https://werkbaum.javagil.de - [^] #ed.live: Live diagram from text (L) - [^] #ed.parser: Parser (S) @@ -52,6 +52,7 @@ - [^] #ed.path.line: Metro-map line through the leaves (S) - [^] #ed.path.step: Step from station to station, one button (S) %% see D47 - [^] #ed.path.load: Warn when one person is the bottleneck (S) %% see D71 + - [ ] #ed.path.worth: The most worthwhile path: one button, three states (M) :#not.benefit - [^] #ed.closure: Count the whole dependency closure (M) - [^] #ed.closure.once: Shared dependencies counted only once (S) - [^] #ed.closure.nonlocal: The cheapest alternative is no longer the local one (M) %% see D34, D42 @@ -341,18 +342,22 @@ the one address an agent tries on its own. #not.benefit - Sizes say what something costs; nothing yet says what it is worth. With both - you could sort by value for money instead of only minimizing cost. + A benefit rating independent of the effort estimate, weighed against it + only at prioritization time. Written inside the size token — (M/9), or + (/7) without a size — one digit 0-9, where 0 marks a precondition that + must be done but has no benefit of its own. A pure author statement: no + aggregation, no conflict check, no estimation — benefit, unlike cost, is + not additive. Spelled out in SPEC §11. #not.benefit.sigil - A separate character next to the size, in the spirit of everything else in - the line. Needs a collision-free sigil, and parentheses, @, # and %% are - taken. + A separate character next to the size was the first idea; it lost to one + token in one corner — (M/9) needs no new sigil, no new badge and leaves + the node corners as they are. #not.benefit.points Put numbers behind the T-shirt sizes and both benefit and effort become - addable. That buys the effort rollup as well, at the price of a mapping - convention the ordinal sizes deliberately avoid today. + addable — at the price of a precision the ordinal sizes deliberately do + not claim. The 0-9 digit keeps the benefit ordinal instead. #ed The browser editor: text on one side, a live diagram on the other, no server @@ -452,6 +457,14 @@ would serialize through that person. Untagged nodes inherit the nearest tagged ancestor, and the person's tag pills turn amber on open path nodes. +#ed.path.worth + The path toggle becomes a three-state button: off, cheapest, most + worthwhile. In the third state an alternative group picks the best + benefit/cost ratio; rated beats unrated, a group with no ratings at all + falls back to cost — without benefit ratings the most worthwhile path IS + the cheapest. Realized stays realized, discarded never counts; line, + stations and inversion keep their mechanics. + #ed.closure The cheapest path pulls every dependency of a needed node into the needed set, and shared targets count only once. That is why an alternative can win