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

refine(pseudo): comment economy — own-line, only when not self-explanatory

Browse Source 
Add rule 2: comment only what the code cannot say itself;
self-explanatory pseudocode needs none. Put any comment on its
own line above the code; reserve trailing end-of-line comments
for the briefest notes (a bare marker, one or two words), since a
column of trailing prose scans worse than a short note above.

Rework rule 4 (markers) so the bare marker rides trailing while
any explanation it needs moves to an own line. Renumber the rule
list (now 1-10) and fix the mechanics->reduce cross-reference.
Iron Law, worked example, frontmatter, and README updated to
match; the example now demonstrates the sparse-comment style.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Brummel
2026-06-04 12:59:29 +02:00
parent 38fe94d3ac
commit 03eeb0c672
2 changed files with 88 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -3
View File
@@ -39,9 +39,12 @@ with a source-file-and-line anchor, marks notable steps with
reference markers the user can point back at, sketches the reference markers the user can point back at, sketches the
layout of the data structures the code touches alongside the layout of the data structures the code touches alongside the
flow, reduces the irrelevant to stubs, and omits low-level flow, reduces the irrelevant to stubs, and omits low-level
mechanics. Prose is allowed only in a supporting role — the mechanics. The pseudocode leans on the source language's idiom
pseudocode block stays the centre of every answer. It dispatches in a language-tagged fence so it renders with syntax
no agents. highlighting, and keeps comments sparse — on their own line and
only where the code is not self-explanatory. Prose is allowed
only in a supporting role — the pseudocode block stays the
centre of every answer. It dispatches no agents.
Vocabulary is configurable. A **cycle** is one round in the Vocabulary is configurable. A **cycle** is one round in the
pipeline graph; your project may call it a *release*, an *epic*, pipeline graph; your project may call it a *release*, an *epic*,
pseudo/SKILL.md
+82 -51
View File
@@ -1,6 +1,6 @@
--- ---
name: pseudo 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); opens with a source-file-and-approximate-line anchor; tags notable steps with reference markers ([1], [A]) the user can point back at; and sketches the layout of the data structures the code touches alongside the control flow. 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]) 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.
--- ---
# pseudo — explain code as commented pseudocode # pseudo — explain code as commented pseudocode
@@ -14,8 +14,11 @@ code. The medium of explanation is **commented pseudocode** —
not the real source, and not prose carrying the explanation on not the real source, and not prose carrying the explanation on
its own. Prose has a place, but a supporting one: it explains its own. Prose has a place, but a supporting one: it explains
what the code cannot show and then gets out of the way. The what the code cannot show and then gets out of the way. The
pseudocode is a teaching artefact: it shows the shape of the pseudocode leans on the source language's idiom and is shown in a
logic at the altitude the question demands, and nothing more. fence tagged with that language, so it highlights in the terminal
and reads in the home language — yet it stays pseudocode: a
teaching artefact that shows the shape of the logic at the
altitude the question demands, and nothing more.
This is a conversational behaviour skill. It dispatches no This is a conversational behaviour skill. It dispatches no
agents and runs no pipeline. While it is active, every answer agents and runs no pipeline. While it is active, every answer
@@ -25,11 +28,13 @@ obeys the rules below.
``` ```
PSEUDOCODE IS THE CENTRE OF EVERY ANSWER; PROSE ONLY SERVES IT. 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. EVERY ANSWER OPENS WITH ITS SOURCE FILE AND APPROXIMATE LINE.
MARK THE NOTABLE POINTS SO THE USER CAN POINT BACK AT THEM. MARK THE NOTABLE POINTS SO THE USER CAN POINT BACK AT THEM.
SHOW ONLY WHAT THE QUESTION IS ABOUT — REDUCE THE REST TO A STUB. 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. SKETCH THE DATA SHAPES THE CODE TOUCHES, NOT JUST THE CONTROL FLOW.
OMIT LOW-LEVEL MECHANICS UNLESS THE QUESTION IS ABOUT THEM. OMIT LOW-LEVEL MECHANICS UNLESS THE QUESTION IS ABOUT THEM.
LEAN ON THE SOURCE LANGUAGE'S IDIOM; TAG THE FENCE SO IT HIGHLIGHTS.
``` ```
## Rules ## Rules
@@ -38,56 +43,73 @@ OMIT LOW-LEVEL MECHANICS UNLESS THE QUESTION IS ABOUT THEM.
pseudocode block is the centre of every reply. Prose *is* pseudocode block is the centre of every reply. Prose *is*
allowed — but only to explain something the code cannot show allowed — but only to explain something the code cannot show
on its own, and it stays subordinate: a short note before or on its own, and it stays subordinate: a short note before or
after the block, never the main event. Reach first for a after the block, never the main event. If a reply is mostly
`# comment` inside the block; spend a sentence of prose only prose with a token snippet, the balance is wrong.
when the point needs more room than a comment gives. If a
reply is mostly prose with a token snippet, the balance is
wrong.
2. **Anchor line first.** The block opens with a `# comment` 2. **Comment only what the code can't say itself.** Pseudocode
that reads clearly needs no comment — self-explanatory names
and structure are the whole point. Add a comment only where
intent, a non-obvious *why*, or a stub is not visible from the
code itself. Put it on its **own line above** the code it
explains; reserve trailing end-of-line comments for the
briefest notes (a bare marker, one or two words). A column of
trailing comments is harder to scan than a short note above
the line — when in doubt, own line.
3. **Anchor line first.** The block opens with a comment — in the
source language's own comment syntax (`//`, `#`, `--`) —
naming the source file and the approximate line the naming the source file and the approximate line the
explanation starts at — e.g. `# src/server.rs ~line 42`. The explanation starts at, e.g. `// src/server.rs ~line 42`. The
line is a navigation hint, not a promise of exactness; "~" line is a navigation hint, not a promise of exactness; "~"
signals that. If the answer spans several files, each new signals that. If the answer spans several files, each new
file's section opens with its own anchor. file's section opens with its own anchor.
3. **Mark the notable points.** Tag the steps worth discussing 4. **Mark the notable points.** Tag the steps worth discussing
with a reference marker — `[1]`, `[2]` or `[A]`, `[B]` — at with a reference marker — `[1]`, `[2]` or `[A]`, `[B]`. The
the end of the line, so the user can reply "expand [2]" or bare marker rides in a trailing comment; any explanation it
"why [B]?" without quoting code. Mark only meaningful points, needs goes on its own line above (rule 2), not strung after
not every line; numbering noise defeats the purpose. 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.
4. **Human-readable, not language-specific.** Use plain 5. **Lean on the source language, but stay pseudocode.** Shape
constructs (`if`, `for each`, `call`, `return`) and real the pseudocode after the source language's idiom and tag the
names from the code where they aid recognition. Do not fenced block with that language — ` ```rust `, ` ```python `,
reproduce the actual source syntax. ` ```go ` — so the terminal renders syntax highlighting and
the reader recognises the home language. This is still
pseudocode, not source: reduced bodies, stubs, and
plain-language placeholders (`for each …`, `… details
elsewhere`) are welcome; it need not compile, and exact syntax
yields to readability whenever the two conflict. If the source
language is unknown or the answer spans several, fall back to a
neutral, highly readable style with a bare fence.
5. **Reduce the irrelevant.** Anything not on the path the user 6. **Reduce the irrelevant.** Anything not on the path the user
asked about collapses to a one-line stub: asked about collapses to a one-line stub:
`validate(input) # details elsewhere`. Detail is spent only `validate(input)` with a brief `details elsewhere` note. Detail
on the topic. is spent only on the topic.
6. **Omit mechanics by default.** Memory management, allocation, 7. **Omit mechanics by default.** Memory management, allocation,
error-propagation plumbing, logging, and similar are left error-propagation plumbing, logging, and similar are left
out — *unless* the question is precisely about them, in which out — *unless* the question is precisely about them, in which
case they become the topic and rule 5 reduces everything else. case they become the topic and rule 6 reduces everything else.
7. **Show the data shapes, not just the flow.** The control 8. **Show the data shapes, not just the flow.** The control
flow is only half the picture; sketch the layout of the data flow is only half the picture; sketch the layout of the data
structures the code in focus reads or builds — the record structures the code in focus reads or builds — the record
fields, the collection nesting, the variant cases that matter fields, the collection nesting, the variant cases that matter
to the question. Put the shape near the code that touches it, to the question. Put the shape near the code that touches it,
in the same reduced spirit: only the fields on the topic path, in the same reduced spirit: only the fields on the topic path,
the rest stubbed (`… # other fields elsewhere`). When the the rest stubbed with a brief `other fields elsewhere` note.
data layout *is* the question, it leads the answer and the When the data layout *is* the question, it leads the answer
control flow becomes the stub. and the control flow becomes the stub.
8. **Default entry point.** When the user names no starting 9. **Default entry point.** When the user names no starting
point, begin at the project's main entry (the `main` function point, begin at the project's main entry (the `main` function
/ primary CLI or server bootstrap). Otherwise start where / primary CLI or server bootstrap). Otherwise start where
they point. they point.
9. **Stay at one altitude; let the user zoom.** There is no 10. **Stay at one altitude; let the user zoom.** There is no
length cap, but each answer holds a single altitude rather length cap, but each answer holds a single altitude rather
than expanding every branch at once. When a level has more than expanding every branch at once. When a level has more
depth than the question needs, show that level and let the depth than the question needs, show that level and let the
@@ -96,31 +118,40 @@ OMIT LOW-LEVEL MECHANICS UNLESS THE QUESTION IS ABOUT THEM.
## Shape of a good answer ## Shape of a good answer
``` The source is Rust, so the fence is tagged `rust` (it highlights
# src/server.rs ~line 30 — how a request reaches a handler in the terminal) and the pseudocode leans on Rust's idiom — while
staying pseudocode: `Vec<{ … }>` is not valid Rust, bodies are
reduced, placeholders stand in for omitted detail.
Router: # [1] the structure match() reads ```rust
routes: list of { path_pattern, handler } // src/server.rs ~line 30 — how a request reaches a handler
… # fallback handler, middleware chain elsewhere
main(): // [1] the structure match() reads; only `routes` is on the path
config = load_config() # details elsewhere struct Router {
router = build_routes() # fills Router.routes routes: Vec<{ path_pattern, handler }>,
serve(router): // fallback handler, middleware chain elsewhere
for each incoming request: }
handler = router.match(request.path) # [2] scans routes
response = handler(request) # [3] fn main() {
send(response) let config = load_config(); // details elsewhere
let router = build_routes();
serve(router, |request| {
let handler = router.match(request.path); // [2]
let response = handler(request); // [3]
send(response);
});
}
``` ```
That is a whole answer. It opens with the file-and-line anchor, That is a whole answer. The code reads itself, so comments are
sketches the `Router` shape `[1]` right beside the code that sparse: a file-and-line anchor, one own-line note explaining the
reads it (only the field on the topic path; the rest stubbed), `Router` shape `[1]`, a short `details elsewhere` stub, and bare
keeps the request path in focus, stubs the config load, omits markers `[2]`/`[3]` trailing the two lines worth pointing at —
the socket and memory mechanics, and marks the discussable no column of end-of-line prose. It tags the fence `rust` for
steps. It holds one altitude: the user can now say "expand [2]" highlighting, keeps the request path in focus, omits the socket
and the next answer zooms into route matching — with its own and memory mechanics, and holds one altitude: the user can now
anchor line. say "expand [2]" and the next answer zooms into route matching,
with its own anchor line.
## When to stop ## When to stop