From 56ecfc7feeb432a1117664df42f0322ccd0212fd Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Thu, 3 Sep 2026 20:46:10 +0200 Subject: [PATCH] docs: stack-dev - Issue-Abschluss als nummerierter Schritt 5, Routing-Blurb rebalanciert (4.3.2, #45) Files changed: - CHANGES.md - VERSION - instructions/dev/stack-dev/SKILL.md --- CHANGES.md | 43 +++++++++++++++++++++++++++++ VERSION | 2 +- instructions/dev/stack-dev/SKILL.md | 30 ++++++++++++++++++-- 3 files changed, 71 insertions(+), 4 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index d818cc9..d3c7ef4 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -20,6 +20,49 @@ their date-only headings. --- +## 4.3.2 - 2026-09-03 - stack-dev: Issue-Abschluss ist ein nummerierter Schritt, kein Zeiger in einer Routing-Liste + +**Author:** Torben Nehmer + +Nachfassen zu 4.1.2 (#44), das die Regel geschaerft, aber den Weg zu ihr nicht geaendert hat. +`instructions/dev/issue-tracking.md` bekam damals Schritt 7 ("Closing is the last body update, +not a comment"); `instructions/dev/stack-dev/SKILL.md` bekam nur eine umformulierte Zeile in +seiner Routing-Liste. Eine Stunde spaeter schloss #45 auf exakt dieselbe Weise: gruendlicher +Abschlusskommentar ueber einem Body mit unangehakten Kriterien. + +**Die Ursache lag nicht am Text der Regel, sondern an ihrer Erreichbarkeit.** Die nummerierten +Schritte des Skills endeten bei "Verify before publishing". Ein Issue zu schliessen war ueberhaupt +kein Schritt - es hing an einem Zeiger *innerhalb* von Schritt 2, und Schritt 2 ist eine +Routing-Tabelle aus fuenf "read X before Y"-Eintraegen, keine Checkliste. Eine Sitzung folgt dem +Spine, den sie im Kontext hat; was nur hinter einem Link steht, wird genau in dem Moment nicht +aufgeschlagen, in dem es greift - am Ende einer langen Sitzung, wenn der Kontext am vollsten und +die verbleibende Instruktionsflaeche am duennsten ist. + +Verschaerfend arbeitete der Blurb gegen seine eigene Regel: fett gesetzt war "keep it current as +the state moves, **not at the end**". Wer den Body unterwegs ungefaehr gepflegt hatte, las daraus +Konformitaet - der eigentliche Abschlusstest stand nur in der verlinkten Datei. + +Geaendert: + +- **Neuer Schritt 5 in `stack-dev/SKILL.md`** - "Close the issue with a body rewrite, not a + comment", mit dem Test inline (Kriterien abgehakt oder mit Begruendung gestrichen, + Entscheidungen als entschieden formuliert, kein Praesens ueber einen behobenen Defekt, + Verifikation benannt) und dem Verweis auf Schritt 7 fuer die volle Form. Damit steht der + Abschluss auf dem Spine. +- **Schritt-2-Blurb rebalanciert** - beide Haelften binden jetzt sichtbar: fortlaufende Pflege + *und* der Rewrite vor dem Schliessen, mit Verweis auf Schritt 5. + +Nichts davon ist maschinell pruefbar, und das bleibt richtig so: `wikitool` kennt den Tracker +nicht und darf ihn nicht lernen, weil es an Instanzen ausliefert, die kein Board haben +(`issue-tracking.md` ยง "What no tool checks"). Der Skill-Spine ist die einzige Durchsetzung, die +es geben kann - was der Grund ist, den Schritt zu nummerieren statt ihn zu verlinken. + +Verallgemeinerbar: eine Regel, die in eine verlinkte Instruction geschrieben wird, erreicht +Sitzungen nur, wenn die nummerierten Schritte des zustaendigen Skills sie in dem Moment +ansteuern, in dem sie greift. + +--- + ## 4.3.1 - 2026-09-03 - docs/ befuellt - Stack-Hintergrund fuer vier Themen, Pflegeklausel in AGENTS.md ergaenzt **Author:** Torben Nehmer diff --git a/VERSION b/VERSION index f77856a..cc2fbe8 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.3.1 +4.3.2 diff --git a/instructions/dev/stack-dev/SKILL.md b/instructions/dev/stack-dev/SKILL.md index fb9e1c7..a3a8d0a 100644 --- a/instructions/dev/stack-dev/SKILL.md +++ b/instructions/dev/stack-dev/SKILL.md @@ -45,9 +45,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li [issue-tracking.md](../issue-tracking.md) - open work lives in Gitea issues, one per work package, labelled `area/`, `kind/`, `prio/` and `size/`. There is no `TODO.md`. **The body of the issue you are working on is this session's plan file:** keep it current as the state - moves, not at the end, so an interrupted session leaves a body the next one can resume from. - Read it before filing something for later, before editing or closing an issue, or before - deciding what to pick up next. + moves, so an interrupted session leaves a body the next one can resume from, *and* rewrite it + to its final state before closing. Both halves bind; the second is step 5 below. Read it + before filing something for later, before editing or closing an issue, or before deciding + what to pick up next. [testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately empty machine; what the autouse fixture already neutralizes, and what a test still has to establish itself. Read it before adding or changing a test. @@ -104,6 +105,29 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li `VERSION` additionally triggers a tagged release. **CI does the tagging** - a session never creates a tag, which is what keeps AGENTS.md invariant 5 intact. +5. **Close the issue with a body rewrite, not a comment.** The last act of a session that + finished a work package, and the one most easily skipped: by here the change is published and + the issue feels done. It is not. The body is the version everyone reads afterwards and nobody + revisits, so it is the one place the debt comes due at the worst moment. + + Rewrite it to its final state *first*, then close. The test is what a reader who opens the + closed issue tomorrow would conclude: + + - every acceptance criterion ticked, or struck with the reason it was dropped + - proposals that were decided read as decided; a "to decide" section has become the decision + and its reasoning + - nothing left in the present tense about a defect that no longer exists + - what was verified is named - which checks ran, which CI run - not a commit hash alone + + Then one short comment naming what changed against the previous state, and nothing else. + + **A closing report in a comment does not satisfy this**, however thorough: it reads as + complete to whoever writes it and leaves a body still phrased as open work. Nothing + mechanical catches it - `wikitool` does not know this tracker exists and must not learn it, + since it ships to instances that have no board - so this step is the only enforcement there + is. #44 and #45 both closed exactly this way, the second an hour after the rule was written. + [issue-tracking.md](../issue-tracking.md) step 7 has the full shape. + ## Decision points - **Touches both stack code and wiki content in one session?** Apply this skill's rules to the