Brummel
ec69e34d1b
Add rule 7: alongside the control flow, sketch the layout of the data structures the code in focus reads or builds — record fields, collection nesting, variant cases relevant to the question — placed beside the code that touches them and reduced in the same spirit (only the fields on the topic path). When the data layout is the question, it leads and the flow becomes the stub. Iron Law, worked example, frontmatter, and README updated to match. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
---
|
|
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, 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.
|
|
---
|
|
|
|
# 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.
|
|
SKETCH THE DATA SHAPES THE CODE TOUCHES, NOT JUST THE CONTROL FLOW.
|
|
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. **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.
|
|
|
|
8. **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. **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
|
|
|
|
Router: # [1] the structure match() reads
|
|
routes: list of { path_pattern, handler }
|
|
… # fallback handler, middleware chain elsewhere
|
|
|
|
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)
|
|
```
|
|
|
|
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, marks the discussable steps,
|
|
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.
|