Skills/pseudo/SKILL.md

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