Skills/pseudo/SKILL.md

name, description

name

description

pseudo

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.

// 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.