refine(pseudo): markers are pointing handles, not footnotes

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) <noreply@anthropic.com>

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
+reference markers that are pointing handles for the user (not
-layout of the data structures the code touches alongside the
+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

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
+   after the block, never the main event. Such a note gives
-   prose with a token snippet, the balance is wrong.
+   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
+   marker is **purely a pointing handle for the user** — a label
-   needs goes on its own line above (rule 2), not strung after
+   so they can reply "expand [2]" or "why [B]?" without quoting
-   the marker. The user can then reply "expand [2]" or "why [B]?"
+   code. It is **not a footnote**. Everything the marked line
-   without quoting code. Mark only meaningful points, not every
+   needs explained is explained *there*, inline, in the comment
-   line; numbering noise defeats the purpose.
+   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
+Note what carries the explanation: it is **inside** the block.
-sparse: a file-and-line anchor, one own-line note explaining the
+`[1]` needs a word of intent, so that word sits on its own line
-`Router` shape `[1]`, a short `details elsewhere` stub, and bare
+right above the struct. `[2]` and `[3]` mark lines that read for
-markers `[2]`/`[3]` trailing the two lines worth pointing at —
+themselves, so they carry no explanation at all — the markers
-no column of end-of-line prose. It tags the fence `rust` for
+are bare, present only so the user can point ("expand [2]").
-highlighting, keeps the request path in focus, omits the socket
+Crucially, **nothing follows the block to decode the markers** —
-and memory mechanics, and holds one altitude: the user can now
+no `[1] = …, [2] = …` legend. Everything a marked line means is
-say "expand [2]" and the next answer zooms into route matching,
+already at that line, so the reader never bounces between code
-with its own anchor line.
+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