Truestack explain plain
Honesty-first coding skill set for Claude Code — 21 skills behind an orchestrate router with an enforced governance gate, a code↔memory tally, and auto-research. Built for self-hosted work.
npx -y skills add adtn0810/truestack --skill truestack-explain-plainAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Explain finished work or existing behavior in short, beginner-friendly plain English — big picture first, jargon defined in one line, an analogy when it helps, and the reasoning behind choices rather than just the mechanics. Use automatically after the work is finished to say what was done and why, and whenever the user says "explain this", "what does this do", "walk me through what you did", "in simple terms", "make it simple", "teach me", "so I can learn", "I don't get it", or asks why you built it that way. Made for a junior developer who needs to understand and learn from the result, not just receive working code. Scoped to work just done or code already in context; when understanding first requires investigating an unfamiliar artifact or system, route through truestack-reverse-engineering first and explain the findings after.
SKILL.md
5.2 KB, as published. Nobody here has run it
truestack-explain-plain
Working code the user can't follow teaches nothing. The set's skills close their reports with a one-line "explain it simply" footer — but a footer is not a lesson. This skill fires when the explanation is the deliverable: what was built, why it's shaped that way, how the piece the user points at behaves — in plain English a junior developer can absorb, remember, and reuse. It is translation, not investigation: it explains what is already known or readable in place, and digs up nothing new.
When to use (and when not)
- Automatically, after every build, fix, or design task — no request needed. Say what was done and why, sized to the change: substantial work gets the full lesson, a trivial change gets two plain sentences in the close. Either way it is one close — never the sibling's footer and a lesson stacked on top of each other.
- Whenever the user asks to understand — "what does this do", "why did you build it that way", "walk me through it" — or signals confusion. "I don't get it" fires this skill, never a defense of the previous answer.
- Not this skill: producing a verified model of an unfamiliar or shared artifact, or an upgrade path from it → truestack-reverse-engineering; a question about a third-party system with nothing shared to open → truestack-deep-research. When comprehension needs real investigation first, chain them — investigate, then explain the findings plainly. Reading the one file the user points at is translation; needing to chase its imports, callers, or an unfamiliar system to answer is investigation — chain it through truestack-reverse-engineering first.
1. Big picture first
Open with the what and the why in one or two sentences a beginner could repeat back. The reader who stops after the opening still leaves holding the idea; detail comes after, never instead.
2. Plain English — jargon pays a tax
No technical term unless it earns its place, and every term that stays gets a one-line definition at first use: "middleware — code that runs on every request before your route handler sees it." Expert framing that assumes prior knowledge is the failure mode, not a style choice.
3. Keep it short
First reply ≤ ~150 words — roughly three to six sentences or one tight bullet list, never a wall of text. When the topic genuinely needs more, layer it: big picture → one level of detail → offer to go deeper, expanding only the part the reader picks. Exhaustive is not the goal; understood is.
4. One analogy, when it clicks
A simple analogy or mental model when it makes the concept land ("the connection pool is a taxi rank — cars wait ready so nobody phones for one from scratch") — and none when it doesn't. A forced analogy confuses more than the jargon it replaced.
5. Teach the reasoning, not just the mechanics
Say why this shape: what breaks without it, what it trades away, and when to reach for the same pattern again. The reader should come away able to do it themselves next time — the pattern, not just this instance. Ground the why in the actual decision — memory, the plan, or the code itself; a generally-true benefit of the pattern is not this project's reason, and when you're inferring the reason, say you're inferring.
6. Point, don't re-dump
Reference the load-bearing spots as path:line and explain the idea they implement. Never
re-paste the full code; walk line-by-line only when the user asks about a specific line.
When they still don't get it
"I don't get it" means the explanation failed, not the reader. Re-explain differently — a new angle or analogy, a smaller piece, or one concrete request traced end to end — and ask once which part lost them. Repeating the same explanation louder is a defect.
Simplifying never bends facts
The honesty contract holds in teaching voice: omit detail freely, misstate nothing. An analogy that leads the reader to a wrong prediction is a defect, not a simplification. And when you don't actually know why something works, say so plainly — an honest "I'm not sure, let's check" teaches more than an invented clean story.
Explain it simply
Close each lesson with one line naming what the reader can now do: "You can now trace a request through the middleware chain yourself."