From 8fbb5c893738619fd830acc6b9e00d24b0d7ce0a Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 12:29:53 +0200 Subject: [PATCH] feat(pseudo): add code-explanation-as-pseudocode skill A user-invoked conversational skill: while active, every reply explains code in commented, human-readable pseudocode instead of prose. Each answer opens with a source-file-and-approximate-line anchor, tags notable steps with reference markers ([1], [A]) the user can point back at, reduces off-topic paths to stubs, omits low-level mechanics unless asked, defaults to the project main entry, and never runs longer than one screen. Dispatches no agents and runs no pipeline; documented in the README as a conversational skill standing outside the pipeline. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 8 ++++ pseudo/SKILL.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 pseudo/SKILL.md diff --git a/README.md b/README.md index 2bd14b8..1cb5ec0 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,14 @@ Two further **utility skills** are invoked on demand rather than as pipeline phases: `issue` (file or update a tracker item) and `glossary` (build or maintain the project glossary — see `docs/glossary-convention.md`). +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, reduces the +irrelevant to stubs, omits low-level mechanics, and never runs +longer than one screen. 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*, or whatever fits, and its sub-unit (the default *iteration*) a diff --git a/pseudo/SKILL.md b/pseudo/SKILL.md new file mode 100644 index 0000000..0ace317 --- /dev/null +++ b/pseudo/SKILL.md @@ -0,0 +1,101 @@ +--- +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 pseudocode only; no prose paragraphs, opens with a source-file-and-approximate-line anchor, and tags notable steps with reference markers ([1], [A]) the user can point back at. 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 + +> **Violating the letter of these rules is violating the spirit.** + +## Overview + +The user wants to understand how code works without reading the +code. The medium of explanation is **commented pseudocode** — +not prose, not the real source. The pseudocode is a teaching +artefact: it 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 +obeys the rules below. + +## The Iron Law + +``` +EVERY ANSWER IS PSEUDOCODE. NO PROSE PARAGRAPHS. +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. +OMIT LOW-LEVEL MECHANICS UNLESS THE QUESTION IS ABOUT THEM. +NEVER LONGER THAN ONE SCREEN. +``` + +## Rules + +1. **Pseudocode is the whole answer.** No introductory sentence, + no closing summary. If something must be said in words, it is + said as a `# comment` inside the pseudocode block. + +2. **Anchor line first.** The block opens with a `# comment` + naming the source file and the approximate line 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. **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. **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. + +6. **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. + +7. **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. + +8. **One screen, hard limit.** No answer exceeds roughly one + screen page. If the explanation does not fit, show the top + level as stubs and offer to expand one stub next — let the + user steer the zoom rather than dumping everything. + +## Shape of a good answer + +``` +# src/server.rs ~line 30 — how a request reaches a handler +main(): + config = load_config() # details elsewhere + router = build_routes() # [1] + serve(router): + for each incoming request: + handler = router.match(request.path) # [2] + response = handler(request) # [3] + send(response) +``` + +That is a whole answer. It opens with the file-and-line anchor, +starts at the entry point, keeps the request path in focus, +stubs the config load, omits the socket and memory mechanics, +marks the three discussable steps `[1]`–`[3]`, and fits one +screen. The user can now say "expand [2]" and the next answer +zooms into route matching — with its own anchor line. + +## When to stop + +The skill stays active for the conversation. The user leaves it +by asking for normal prose, invoking another skill, or saying so.