--- 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]) 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 > **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 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 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 obeys the rules below. ## The Iron Law ``` 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. LEAN ON THE SOURCE LANGUAGE'S IDIOM; TAG THE FENCE SO IT HIGHLIGHTS. ``` ## Rules 1. **Pseudocode carries the answer; prose serves it.** The 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. 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 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 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. 4. **Mark the notable points.** Tag the steps worth discussing with a reference marker — `[1]`, `[2]` or `[A]`, `[B]`. The 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 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. 6. **Reduce the irrelevant.** Anything not on the path the user asked about collapses to a one-line stub: `validate(input)` with a brief `details elsewhere` note. Detail is spent only on the topic. 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 6 reduces everything else. 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 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. 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. 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 markers invite the user to expand one point next — steer the zoom with them rather than dumping every layer unprompted. ## Shape of a good answer 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. ```rust // src/server.rs ~line 30 — how a request reaches a handler // [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); }); } ``` 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 The skill stays active for the conversation. The user leaves it by asking for a plain prose explanation (one not built around a pseudocode block), invoking another skill, or saying so.