From 03eeb0c672c3a86c28cc148bc77b555340c5d104 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 12:59:29 +0200 Subject: [PATCH] =?UTF-8?q?refine(pseudo):=20comment=20economy=20=E2=80=94?= =?UTF-8?q?=20own-line,=20only=20when=20not=20self-explanatory?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- README.md | 9 ++-- pseudo/SKILL.md | 133 +++++++++++++++++++++++++++++------------------- 2 files changed, 88 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 8dc54e9..d12d82e 100644 --- a/README.md +++ b/README.md @@ -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*, diff --git a/pseudo/SKILL.md b/pseudo/SKILL.md index 63cd058..2c386d9 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); 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