From ac3e718cb297d0aa3c2de0a02fe812540ad91bcd Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 14:26:04 +0200 Subject: [PATCH] refine(pseudo): markers are pointing handles, not footnotes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forbid the footnote/legend pattern: explanations for a marked line must live inline at that line (rule 2), never in a post-block `[1] = …, [2] = …` key that forces the reader to bounce between code and a legend below it. A marker is purely a label so the user can point ('expand [2]'); a line that reads for itself carries a bare marker and no comment. Rework rule 4 accordingly, add the Iron Law line, guard rule 1's supporting-prose clause against becoming a legend, and rewrite the worked example's trailing commentary to demonstrate inline explanation with no marker key. Frontmatter and README updated. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 6 ++++-- pseudo/SKILL.md | 48 +++++++++++++++++++++++++++++++----------------- 2 files changed, 35 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index d12d82e..b52e37d 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,10 @@ One **conversational skill** stands outside the pipeline entirely: `pseudo` (typed `/pseudo`) switches replies into commented, human-readable pseudocode for explaining code — each answer opens with a source-file-and-line anchor, marks notable steps with -reference markers the user can point back at, sketches the -layout of the data structures the code touches alongside the +reference markers that are pointing handles for the user (not +footnotes — explanations stay inline at the code, never in a +legend below), sketches the layout of the data structures the +code touches alongside the flow, reduces the irrelevant to stubs, and omits low-level mechanics. The pseudocode leans on the source language's idiom in a language-tagged fence so it renders with syntax diff --git a/pseudo/SKILL.md b/pseudo/SKILL.md index 2c386d9..8cc6256 100644 --- a/pseudo/SKILL.md +++ b/pseudo/SKILL.md @@ -1,6 +1,6 @@ --- name: pseudo -description: Use when the user wants code explained in human-readable, commented pseudocode rather than prose — invoked as `/pseudo` or when the user asks to "explain this in pseudocode". Every reply is centred on a pseudocode block (prose is allowed, but only in a supporting role to explain what the code cannot show); keeps comments sparse — on their own line and only where the code is not self-explanatory; opens with a source-file-and-approximate-line anchor; tags notable steps with reference markers ([1], [A]) the user can point back at; sketches the layout of the data structures the code touches alongside the control flow; and leans on the source language's idiom in a language-tagged fence so it renders with syntax highlighting (while staying pseudocode, not compilable source). Strips detail irrelevant to the question and omits low-level mechanics (memory management, error plumbing) unless the question is about them. Defaults to the project's main entry point. +description: Use when the user wants code explained in human-readable, commented pseudocode rather than prose — invoked as `/pseudo` or when the user asks to "explain this in pseudocode". Every reply is centred on a pseudocode block (prose is allowed, but only in a supporting role to explain what the code cannot show); keeps comments sparse — on their own line and only where the code is not self-explanatory; opens with a source-file-and-approximate-line anchor; tags notable steps with reference markers ([1], [A]) that are pointing handles for the user, not footnotes — every explanation stays inline at its line, never in a legend below the block; sketches the layout of the data structures the code touches alongside the control flow; and leans on the source language's idiom in a language-tagged fence so it renders with syntax highlighting (while staying pseudocode, not compilable source). Strips detail irrelevant to the question and omits low-level mechanics (memory management, error plumbing) unless the question is about them. Defaults to the project's main entry point. --- # pseudo — explain code as commented pseudocode @@ -31,6 +31,7 @@ PSEUDOCODE IS THE CENTRE OF EVERY ANSWER; PROSE ONLY SERVES IT. COMMENT ONLY WHAT THE CODE CAN'T SAY ITSELF; A LINE ABOVE BEATS A TRAILING NOTE. EVERY ANSWER OPENS WITH ITS SOURCE FILE AND APPROXIMATE LINE. MARK THE NOTABLE POINTS SO THE USER CAN POINT BACK AT THEM. +MARKERS ARE POINTING HANDLES, NOT FOOTNOTES — EXPLAIN AT THE CODE, NEVER IN A LEGEND BELOW. SHOW ONLY WHAT THE QUESTION IS ABOUT — REDUCE THE REST TO A STUB. SKETCH THE DATA SHAPES THE CODE TOUCHES, NOT JUST THE CONTROL FLOW. OMIT LOW-LEVEL MECHANICS UNLESS THE QUESTION IS ABOUT THEM. @@ -43,8 +44,11 @@ LEAN ON THE SOURCE LANGUAGE'S IDIOM; TAG THE FENCE SO IT HIGHLIGHTS. pseudocode block is the centre of every reply. Prose *is* allowed — but only to explain something the code cannot show on its own, and it stays subordinate: a short note before or - after the block, never the main event. If a reply is mostly - prose with a token snippet, the balance is wrong. + after the block, never the main event. Such a note gives + context the code cannot carry; it never decodes the markers + line by line (that is a footnote legend — see rule 4). If a + reply is mostly prose with a token snippet, the balance is + wrong. 2. **Comment only what the code can't say itself.** Pseudocode that reads clearly needs no comment — self-explanatory names @@ -66,11 +70,17 @@ LEAN ON THE SOURCE LANGUAGE'S IDIOM; TAG THE FENCE SO IT HIGHLIGHTS. 4. **Mark the notable points.** Tag the steps worth discussing with a reference marker — `[1]`, `[2]` or `[A]`, `[B]`. The - bare marker rides in a trailing comment; any explanation it - needs goes on its own line above (rule 2), not strung after - the marker. The user can then reply "expand [2]" or "why [B]?" - without quoting code. Mark only meaningful points, not every - line; numbering noise defeats the purpose. + marker is **purely a pointing handle for the user** — a label + so they can reply "expand [2]" or "why [B]?" without quoting + code. It is **not a footnote**. Everything the marked line + needs explained is explained *there*, inline, in the comment + at that line (rule 2). Never follow the block with a legend or + footnote list that re-states each marker — that forces the + reader to bounce between the code and a key below it, which is + exactly what inline explanation avoids. If a point cannot be + explained at its line, the answer is at the wrong altitude + (rule 10), not in need of a footnote. Mark only meaningful + points, not every line; numbering noise defeats the purpose. 5. **Lean on the source language, but stay pseudocode.** Shape the pseudocode after the source language's idiom and tag the @@ -143,15 +153,19 @@ fn main() { } ``` -That is a whole answer. The code reads itself, so comments are -sparse: a file-and-line anchor, one own-line note explaining the -`Router` shape `[1]`, a short `details elsewhere` stub, and bare -markers `[2]`/`[3]` trailing the two lines worth pointing at — -no column of end-of-line prose. It tags the fence `rust` for -highlighting, keeps the request path in focus, omits the socket -and memory mechanics, and holds one altitude: the user can now -say "expand [2]" and the next answer zooms into route matching, -with its own anchor line. +Note what carries the explanation: it is **inside** the block. +`[1]` needs a word of intent, so that word sits on its own line +right above the struct. `[2]` and `[3]` mark lines that read for +themselves, so they carry no explanation at all — the markers +are bare, present only so the user can point ("expand [2]"). +Crucially, **nothing follows the block to decode the markers** — +no `[1] = …, [2] = …` legend. Everything a marked line means is +already at that line, so the reader never bounces between code +and a key below it. + +(The paragraph you are reading is commentary on the example, not +part of the answer. A real reply is the fenced block, optionally +a sentence of supporting prose — never a marker legend.) ## When to stop