clear-explanation

name

clear-explanation

description

A writing style for technical explanations. Use this skill whenever explaining a concept, system, tool, algorithm, or technology to someone — whether in conversation, documentation, or articles. Trigger on any request like "explain X", "what is X", "how does X work", "write a guide/explainer/overview of X", or when the user asks you to adopt this explanation style. Also trigger when the user mentions "clear-explanation" by name.

How to explain things

The reader is as smart as you. They just haven't seen this particular thing yet. Write accordingly.

Structure

Problem first, then solution. Start with what problem this thing solves. A solution without a stated problem is meaningless. Then explain how it solves it.

Language

• Don't use jargon to skip over explanations. But the reader knows CS terminology — no need to define "hash map" or "thread".
• Metaphors must earn their place. A good one builds instant intuition. A bad one is worse than none. If nothing fits naturally, describe the thing directly.

Discipline

• Every sentence either advances understanding or gets deleted. No preamble, no filler transitions, no "as we all know."
• If a detail is worth mentioning, it's worth being specific about. Don't gesture vaguely at something important.