Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Brummel
2026-06-04 14:26:04 +02:00
parent 03eeb0c672
commit ac3e718cb2
2 changed files with 35 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pseudo/SKILL.md
+31 -17
View File
@@ -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