wiki-ingest traegt Begruendungsprosa, die instructions/CONTRACT.md aus dem Body verbannt #79

Closed
opened 2026-09-09 09:03:25 +00:00 by torben · 1 comment
Owner

Entscheidung: Weg 3 fuer die Doppelung, Weg 2 fuer den Rest

Vom Operator am 2026-09-09 entschieden, umgesetzt in 663b1c0, Version 4.8.0-beta.10.

Die Begruendungsabsaetze wandern nicht nach kb/concepts/. Stattdessen zwei Dinge:

1. Der Contract sagt jetzt messbar, wieviel Begruendung ein Schritt tragen darf. Das alte Bullet ("Keep reasoning out of the body […] Keep only enough reasoning to decide edge cases") zog in zwei Richtungen und liess die Frage offen, wo die Grenze verlaeuft. instructions/CONTRACT.md § "Writing an instruction" traegt jetzt:

  • ein umformuliertes Bullet: "Reasoning earns its place by deciding something." - behalten, was ein Agent braucht, um diese Entscheidung richtig zu treffen, an dem Schritt, an dem sie faellt; streichen, warum es den Schritt ueberhaupt gibt;
  • den Unterabschnitt "How much reasoning a step may carry" mit einer Keep/Cut-Tabelle und zwei Tests:
    • Substitution - die Passage streichen und den Schritt noch einmal lesen. Trifft ein Agent ohne Vorkontext dieselbe Entscheidung? Dann war es Hintergrund. Raet er jetzt, war es eine Entscheidungshilfe - und sie bleibt, egal wie lang sie ist.
    • Once - eine Entscheidungshilfe steht an dem Schritt, an dem die Entscheidung faellt, und an genau einem solchen (AGENTS.md Invariante 8). Faellt dieselbe Entscheidung an zwei Schritten, steht die Begruendung am ersten und der zweite traegt die Anweisung plus Verweis.

Der Abschnitt schliesst mit dem Satz, der den urspruenglichen Befund aufloest: "A passage that survives both is not an exception to the rule. Deciding an edge case is the part the rule keeps; the length it takes to do that is not the measure."

2. Die Doppelung ist weg. Die source_type/Capture-Asymmetrie stand zweimal im selben Dokument. Sie steht jetzt einmal.

Was in wiki-ingest geaendert wurde

Schritt 1 (vorher Z. 27-33, acht Zeilen): gekuerzt auf fuenf. Der Verweis auf die Asymmetrie mit source_type faellt raus; was bleibt, ist die wirksame Haelfte - ein geratener Capture-Wert ist nicht "unknown", sondern eine Behauptung ueber die Erfassung, die nichts spaeter korrigieren kann, weil das Wissen nur an diesem Drop-Punkt existiert. Plus: "there is no plausible-looking default to fall back on".

Schritt 6 (vorher Z. 101-107): der Satzteil "but unlike source_type there is no catalog slot to fall back on" - die zweite Nennung der Asymmetrie - wurde zu "but here there is no catalog slot to fall back on, for the reason step 1 gives". Genau die Form, die der neue Once-Test verlangt: Anweisung plus Verweis, keine zweite Erzaehlung. Der operative Rest (die von raw accept gedruckte Paarung wiederverwenden, sonst fragen, nie unknown) bleibt unveraendert.

Nebenbei mitgezogen: der Link in Schritt 6 auf kb/sources/COLLECTION.md war ein blosses "read X first". Er sagt jetzt, was daraus zu entnehmen ist - die Auflage aus #72, an der Datei angewandt, die diese Sitzung ohnehin anfasste.

Was geprueft und behalten wurde

Die beiden anderen in diesem Issue genannten Stellen wurden gegen den neuen Substitutionstest gemessen und bestehen ihn:

  • Namenskollision, Schritt 1 (Z. 44-51): ohne den Absatz benennt eine Sitzung die Datei in incoming/ um oder setzt --replaces, statt anzuhalten. Der Satz "that is not this session's call to make: whether the incoming file is a later edition […] is a judgment about the world" ist das, was den Halt ausloest. Entscheidungshilfe, bleibt.
  • ## Not Extracted, Schritt 6: "Nothing in the repository can re-derive that judgment, and without it the same source gets re-litigated on the next pass" entscheidet, wie ausfuehrlich das Feld gefuellt wird. Zwei Zeilen, bleibt.

Das ist die inhaltliche Antwort auf den urspruenglichen Befund: von den vier gemeldeten Stellen war genau eine echte Doppelung. Die anderen drei sind das, was der Contract ausdruecklich behalten will - er sagte es bloss nicht deutlich genug, um daran messbar zu sein.

Befund (Ausgangslage)

instructions/CONTRACT.md § "Writing an instruction" verlangte: "Keep reasoning out of the body. Cut the explanation of why each step exists. If it is worth preserving, it is a concept page under kb/concepts/, linked from here. Keep only enough reasoning to decide edge cases."

instructions/wiki-ingest/SKILL.md hielt sich daran nicht. Zwei Stellen waren mehrsaetzige Begruendungsabsaetze: Z. 27-33 (Schritt 1) und Z. 95-107 (Schritt 6) - dieselbe Asymmetrie zweimal, aus je einer Richtung. Dazu Z. 44-51 und Z. 118-120. Die Datei war mit 214 Zeilen die groesste der fuenf.

Akzeptanzkriterien

  • Es ist entschieden und in instructions/CONTRACT.md nachlesbar, wieviel Begruendung ein Schritt tragen darf - so, dass die beiden Stellen in wiki-ingest daran messbar sind. Der Unterabschnitt nennt wiki-ingest Schritt 1/6 namentlich als Beispiel des Once-Tests.
  • Die Asymmetrie zwischen source_type und den Capture-Werten steht in instructions/wiki-ingest/SKILL.md genau einmal, nicht zweimal.
  • Die Entscheidungshilfe, die verhindert, dass --fidelity/--authority geraten werden, ist nach der Aenderung an der Stelle wirksam, an der die Entscheidung faellt - an beiden Stellen (Schritt 1 traegt sie, Schritt 6 traegt die Anweisung plus Verweis), und in keiner nur verlinkten Datei.
  • instructions/wiki-ingest/SKILL.md bleibt unter 500 Zeilen: 214 → 211.
  • tools/wikitool instructions verify und tools/wikitool docs verify laufen ohne neue Findings. Dazu pytest: 1076 passed.

Geaendert

instructions/CONTRACT.md (Bullet 4 und neuer Unterabschnitt "How much reasoning a step may carry"), instructions/wiki-ingest/SKILL.md (Schritte 1 und 6).

Herkunft

Analyse aus #65, Sitzung 2026-09-09. Bei der Volltext-Sichtung von wiki-ingest aufgefallen; in #65 nicht enthalten. Beruehrte #72 (Referenztiefe), weil Weg 1 die Kette verlaengert haette - #72 fiel auf Weg 2, womit dieses Argument gegen Weg 1 hier zusaetzlich Gewicht bekam. Umgesetzt in derselben Sitzung wie #71 und #72.

## Entscheidung: Weg 3 fuer die Doppelung, Weg 2 fuer den Rest Vom Operator am 2026-09-09 entschieden, umgesetzt in `663b1c0`, Version `4.8.0-beta.10`. Die Begruendungsabsaetze wandern **nicht** nach `kb/concepts/`. Stattdessen zwei Dinge: **1. Der Contract sagt jetzt messbar, wieviel Begruendung ein Schritt tragen darf.** Das alte Bullet ("Keep reasoning out of the body […] Keep only enough reasoning to decide edge cases") zog in zwei Richtungen und liess die Frage offen, wo die Grenze verlaeuft. `instructions/CONTRACT.md` § "Writing an instruction" traegt jetzt: - ein umformuliertes Bullet: **"Reasoning earns its place by deciding something."** - behalten, was ein Agent braucht, um *diese* Entscheidung richtig zu treffen, an dem Schritt, an dem sie faellt; streichen, warum es den Schritt ueberhaupt gibt; - den Unterabschnitt **"How much reasoning a step may carry"** mit einer Keep/Cut-Tabelle und zwei Tests: - **Substitution** - die Passage streichen und den Schritt noch einmal lesen. Trifft ein Agent ohne Vorkontext dieselbe Entscheidung? Dann war es Hintergrund. Raet er jetzt, war es eine Entscheidungshilfe - und sie bleibt, egal wie lang sie ist. - **Once** - eine Entscheidungshilfe steht an dem Schritt, an dem die Entscheidung faellt, und an genau einem solchen (AGENTS.md Invariante 8). Faellt dieselbe Entscheidung an zwei Schritten, steht die Begruendung am ersten und der zweite traegt die Anweisung plus Verweis. Der Abschnitt schliesst mit dem Satz, der den urspruenglichen Befund aufloest: "A passage that survives both is not an exception to the rule. Deciding an edge case is the part the rule keeps; the length it takes to do that is not the measure." **2. Die Doppelung ist weg.** Die `source_type`/Capture-Asymmetrie stand zweimal im selben Dokument. Sie steht jetzt einmal. ## Was in `wiki-ingest` geaendert wurde **Schritt 1** (vorher Z. 27-33, acht Zeilen): gekuerzt auf fuenf. Der Verweis auf die Asymmetrie mit `source_type` faellt raus; was bleibt, ist die wirksame Haelfte - ein geratener Capture-Wert ist nicht "unknown", sondern eine Behauptung ueber die Erfassung, die nichts spaeter korrigieren kann, weil das Wissen nur an diesem Drop-Punkt existiert. Plus: "there is no plausible-looking default to fall back on". **Schritt 6** (vorher Z. 101-107): der Satzteil "but unlike `source_type` there is no catalog slot to fall back on" - die zweite Nennung der Asymmetrie - wurde zu "but here there is no catalog slot to fall back on, **for the reason step 1 gives**". Genau die Form, die der neue *Once*-Test verlangt: Anweisung plus Verweis, keine zweite Erzaehlung. Der operative Rest (die von `raw accept` gedruckte Paarung wiederverwenden, sonst fragen, nie `unknown`) bleibt unveraendert. **Nebenbei mitgezogen:** der Link in Schritt 6 auf `kb/sources/COLLECTION.md` war ein blosses "read X first". Er sagt jetzt, was daraus zu entnehmen ist - die Auflage aus #72, an der Datei angewandt, die diese Sitzung ohnehin anfasste. ## Was geprueft und **behalten** wurde Die beiden anderen in diesem Issue genannten Stellen wurden gegen den neuen Substitutionstest gemessen und bestehen ihn: - **Namenskollision, Schritt 1** (Z. 44-51): ohne den Absatz benennt eine Sitzung die Datei in `incoming/` um oder setzt `--replaces`, statt anzuhalten. Der Satz "that is not this session's call to make: whether the incoming file is a later edition […] is a judgment about the world" ist das, was den Halt ausloest. Entscheidungshilfe, bleibt. - **`## Not Extracted`, Schritt 6**: "Nothing in the repository can re-derive that judgment, and without it the same source gets re-litigated on the next pass" entscheidet, wie ausfuehrlich das Feld gefuellt wird. Zwei Zeilen, bleibt. Das ist die inhaltliche Antwort auf den urspruenglichen Befund: von den vier gemeldeten Stellen war genau eine echte Doppelung. Die anderen drei sind das, was der Contract ausdruecklich behalten will - er sagte es bloss nicht deutlich genug, um daran messbar zu sein. ## Befund (Ausgangslage) `instructions/CONTRACT.md` § "Writing an instruction" verlangte: "**Keep reasoning out of the body.** Cut the explanation of *why* each step exists. If it is worth preserving, it is a concept page under `kb/concepts/`, linked from here. Keep only enough reasoning to decide edge cases." `instructions/wiki-ingest/SKILL.md` hielt sich daran nicht. Zwei Stellen waren mehrsaetzige Begruendungsabsaetze: Z. 27-33 (Schritt 1) und Z. 95-107 (Schritt 6) - dieselbe Asymmetrie zweimal, aus je einer Richtung. Dazu Z. 44-51 und Z. 118-120. Die Datei war mit 214 Zeilen die groesste der fuenf. ## Akzeptanzkriterien - [x] Es ist entschieden und in `instructions/CONTRACT.md` nachlesbar, wieviel Begruendung ein Schritt tragen darf - so, dass die beiden Stellen in `wiki-ingest` daran messbar sind. Der Unterabschnitt nennt `wiki-ingest` Schritt 1/6 namentlich als Beispiel des *Once*-Tests. - [x] Die Asymmetrie zwischen `source_type` und den Capture-Werten steht in `instructions/wiki-ingest/SKILL.md` genau einmal, nicht zweimal. - [x] Die Entscheidungshilfe, die verhindert, dass `--fidelity`/`--authority` geraten werden, ist nach der Aenderung an der Stelle wirksam, an der die Entscheidung faellt - an beiden Stellen (Schritt 1 traegt sie, Schritt 6 traegt die Anweisung plus Verweis), und in keiner nur verlinkten Datei. - [x] `instructions/wiki-ingest/SKILL.md` bleibt unter 500 Zeilen: 214 → 211. - [x] `tools/wikitool instructions verify` und `tools/wikitool docs verify` laufen ohne neue Findings. Dazu `pytest`: 1076 passed. ## Geaendert `instructions/CONTRACT.md` (Bullet 4 und neuer Unterabschnitt "How much reasoning a step may carry"), `instructions/wiki-ingest/SKILL.md` (Schritte 1 und 6). ## Herkunft Analyse aus #65, Sitzung 2026-09-09. Bei der Volltext-Sichtung von `wiki-ingest` aufgefallen; in #65 nicht enthalten. Beruehrte #72 (Referenztiefe), weil Weg 1 die Kette verlaengert haette - #72 fiel auf Weg 2, womit dieses Argument gegen Weg 1 hier zusaetzlich Gewicht bekam. Umgesetzt in derselben Sitzung wie #71 und #72.
torben added the prio/plannedsize/Marea/processkind/decision labels 2026-09-09 09:03:25 +00:00
torben added kind/build and removed kind/decision labels 2026-09-09 14:31:10 +00:00
Author
Owner

Changelog: § "Warum das keine reine Streichuebung ist" (drei moegliche Ausgaenge) ist durch die getroffene Entscheidung ersetzt - Weg 3 fuer die Doppelung, Weg 2 fuer den Rest, vom Operator bestaetigt. Neu: was konkret in wiki-ingest Schritt 1 und 6 geaendert wurde, und ein eigener Abschnitt zu den beiden Stellen, die gegen den neuen Substitutionstest geprueft und behalten wurden (Namenskollision, ## Not Extracted) - von den vier gemeldeten Stellen war genau eine echte Doppelung. Mitgezogen, weil die Datei ohnehin offen war: der Link auf kb/sources/COLLECTION.md sagt jetzt, was daraus zu entnehmen ist (Auflage aus #72). Alle fuenf Akzeptanzkriterien abgehakt, 214 → 211 Zeilen. kind/decisionkind/build. Umgesetzt in 663b1c0, 4.8.0-beta.10. Geschlossen.

**Changelog:** § "Warum das keine reine Streichuebung ist" (drei moegliche Ausgaenge) ist durch die getroffene Entscheidung ersetzt - Weg 3 fuer die Doppelung, Weg 2 fuer den Rest, vom Operator bestaetigt. Neu: was konkret in `wiki-ingest` Schritt 1 und 6 geaendert wurde, und ein eigener Abschnitt zu den beiden Stellen, die gegen den neuen Substitutionstest geprueft und **behalten** wurden (Namenskollision, `## Not Extracted`) - von den vier gemeldeten Stellen war genau eine echte Doppelung. Mitgezogen, weil die Datei ohnehin offen war: der Link auf `kb/sources/COLLECTION.md` sagt jetzt, was daraus zu entnehmen ist (Auflage aus #72). Alle fuenf Akzeptanzkriterien abgehakt, 214 → 211 Zeilen. `kind/decision` → `kind/build`. Umgesetzt in `663b1c0`, `4.8.0-beta.10`. Geschlossen.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#79