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
layout of the data structures the code touches alongside the
flow, reduces the irrelevant to stubs, and omits low-level
mechanics. Prose is allowed only in a supporting role — the
pseudocode block stays the centre of every answer. It dispatches
no agents.
mechanics. The pseudocode leans on the source language's idiom
in a language-tagged fence so it renders with syntax
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
pipeline graph; your project may call it a *release*, an *epic*,
pseudo/SKILL.md
+82 -51
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); 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
@@ -14,8 +14,11 @@ code. The medium of explanation is **commented pseudocode** —
not the real source, and not prose carrying the explanation on
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
pseudocode is a teaching artefact: it shows the shape of the
logic at the altitude the question demands, and nothing more.
pseudocode leans on the source language's idiom and is shown in a
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
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.
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.
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.
LEAN ON THE SOURCE LANGUAGE'S IDIOM; TAG THE FENCE SO IT HIGHLIGHTS.
```
## 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*
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. Reach first for a
`# comment` inside the block; spend a sentence of prose only
when the point needs more room than a comment gives. If a
reply is mostly prose with a token snippet, the balance is
wrong.
after the block, never the main event. 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
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; "~"
signals that. If the answer spans several files, each new
file's section opens with its own anchor.
3. **Mark the notable points.** Tag the steps worth discussing
with a reference marker — `[1]`, `[2]` or `[A]`, `[B]` — at
the end of the line, so the user can reply "expand [2]" or
"why [B]?" without quoting code. Mark only meaningful points,
not every line; numbering noise defeats the purpose.
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.
4. **Human-readable, not language-specific.** Use plain
constructs (`if`, `for each`, `call`, `return`) and real
names from the code where they aid recognition. Do not
reproduce the actual source syntax.
5. **Lean on the source language, but stay pseudocode.** Shape
the pseudocode after the source language's idiom and tag the
fenced block with that language — ` ```rust `, ` ```python `,
` ```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:
`validate(input) # details elsewhere`. Detail is spent only
on the topic.
`validate(input)` with a brief `details elsewhere` note. Detail
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
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
structures the code in focus reads or builds — the record
fields, the collection nesting, the variant cases that matter
to the question. Put the shape near the code that touches it,
in the same reduced spirit: only the fields on the topic path,
the rest stubbed (`… # other fields elsewhere`). When the
data layout *is* the question, it leads the answer and the
control flow becomes the stub.
the rest stubbed with a brief `other fields elsewhere` note.
When the data layout *is* the question, it leads the answer
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
/ primary CLI or server bootstrap). Otherwise start where
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
than expanding every branch at once. When a level has more
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
```
# src/server.rs ~line 30 — how a request reaches a handler
The source is Rust, so the fence is tagged `rust` (it highlights
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
routes: list of { path_pattern, handler }
… # fallback handler, middleware chain elsewhere
```rust
// src/server.rs ~line 30 — how a request reaches a handler
main():
config = load_config() # details elsewhere
router = build_routes() # fills Router.routes
serve(router):
for each incoming request:
handler = router.match(request.path) # [2] scans routes
response = handler(request) # [3]
send(response)
// [1] the structure match() reads; only `routes` is on the path
struct Router {
routes: Vec<{ path_pattern, handler }>,
// fallback handler, middleware chain elsewhere
}
fn main() {
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,
sketches the `Router` shape `[1]` right beside the code that
reads it (only the field on the topic path; the rest stubbed),
keeps the request path in focus, stubs the config load, omits
the socket and memory mechanics, and marks the discussable
steps. It holds one altitude: the user can now say "expand [2]"
and the next answer zooms into route matching — with its own
anchor line.
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.
## When to stop