Explain to me

When to use

• The user asks to explain, clarify, or teach a concept.
• Writing or revising inline code comments that carry meaning.
• Drafting explanatory documentation (how something works, why a choice was made).
• Any prose whose job is to help a reader understand, not to sell or fill space.

For full site docs under web/ (concept articles, READMEs, changelogs, release notes), also use the matching structure skill. Product docs under web/docs/ and roadmap or security feature-status copy use docs-writing. Learn articles under web/learn/ use writing. Those skills own article structure, accuracy rules, and interlinking. This skill owns the voice. Read this skill first whenever voice, banlists, Orwell, or ASD-STE100 apply.

Read web/STYLE_GUIDE.md as the formatting baseline for published docs. Where the two agree on formatting, the style guide wins. Where you need the voice itself, use this.

The voice, in one paragraph

You are explaining something to a peer senior engineer who is smart but new to this specific topic. Second person. Confident and declarative. State the mechanism before its implication, so the reader understands why before they are told what it means. Use one earned metaphor where it makes an abstract idea concrete, not for decoration. Sharpen a point with contrast when a distinction matters. The writing is engaging because it is clear and has a point of view, not because it is hyped. Trust the reader to keep up. The underlying discipline comes from Orwell's rules and ASD-STE100. Cut every word that does not carry weight. Make each sentence mean only one thing. references/principles.md covers both, plus where software terminology is exempt.

Voice rules

• Direct and declarative. One idea per sentence where you can.
• Active voice. "The service dispatches the alert", not "the alert is dispatched".
• Second person when addressing the reader.
• Mechanism before implication.
• Earn every metaphor. If it does not make an idea more concrete, cut it.
• If a word can come out without changing the meaning, take it out.
• Sentences aim for 20 words, 30 is the ceiling. Split anything longer.
• One name per concept, used consistently. Do not alternate synonyms for the same referent in one explanation. Keep precise software terms. Drop vague jargon. See references/principles.md.
• No hedging or qualifiers: "quite", "fairly", "relatively", "somewhat".
• No apologetic openers: "it should be noted that", "it is worth mentioning".
• Paragraphs 3 to 4 sentences. Longer means break it up or use a list.
• Headings organize longer explanations. Do not use prose to transition between sections.
• Do not end a paragraph with a sentence shorter than three words. Fragments like "Coordinate those operations." or "Isolation is the fix." read as abrupt commands, not natural prose. Fold the point into the previous sentence or expand it.

Hard bans: formatting

• No em dashes. Use a period, comma, or colon.
• No semicolons. Break into two sentences.
• No ALL CAPS.
• Minimal parentheses. If the information matters, give it a full sentence.
• Backticks for code, file paths, commands, and identifiers: jj log, type.

Explaining in context

Match length and shape to the job.

For comments: explain non-obvious intent, constraints, or invariants. Do not narrate the code. "Retry on 429 because the upstream rate-limits by IP" earns its keep. "Loop over the items" does not.

Quick check before you return an explanation

1. One claim per sentence. Active voice. No word that can be cut.
2. No hard bans (em dash, semicolon, ALL CAPS), no Tier 1 buzzwords, no AI tells (references/banlists.md).
3. Precise software terms kept. Vague jargon dropped. One name per concept.
4. Mechanism stated before implication. Reader can act or understand without a second pass.
5. For longer drafts, run the checker script below.

References

Load these when the task needs them, not up front:

• references/banlists.md: Tier 1 and Tier 2 buzzwords with replacements, and the full AI-tell catalogue. Read before drafting anything longer than a code comment, or when the checker flags a hit you need to fix.
• references/principles.md: Orwell's six rules, the ASD-STE100 rules, and where software terms are exempt. Read when a rule above is unclear or you need to justify an edit.
• references/exemplars.md: annotated good and bad passages from a real treq article. Read when drafting a new article or when the voice is not landing.

Readability checker script

scripts/readability.py is a dependency-free checker. Run it on any draft:

python3 .claude/skills/explain-to-me/scripts/readability.py path/to/doc.mdx
# --strict exits non-zero on a hard fail (em dash, semicolon, ALL CAPS,
# Tier 1 word, or em-dash rate over 3 per 500 words). Use in a hook or CI.

The checker reports Flesch Reading Ease and grade, sentence-length variation, em-dash and tell density, and every hard-ban, banlist, and AI-tell hit with line numbers. A clean draft has no hard fails, no AI tells, and reading ease at or above 50. Tier 2 words and Title Case headings are review-only signals.