elintp · Explain things clearly, not talk down to the reader
Input: $ARGUMENTS
Goal: After reading, the reader can retell the subject in their own words.
Two kinds of input
Input is a topic (a system, a concept, an incident): organize the content yourself and write according to the guidelines below.
Input is a document (a file path, a link, or pasted body text — PRD, development plan, technical proposal, review minutes, RFC): read the original fully first, determine what type it is and what it's about, set the focus, then rewrite it as HTML using the same set of guidelines. The output format, red lines, and writing guidelines are all identical — there are just two extra constraints: determine the type before setting the focus, and you are restating, not creating.
If you can't tell whether the user gave a topic or a document, ask once — don't guess.
Language choice
If the user hasn't specified a language, use Simplified Chinese; otherwise use the language the user asks in; in document mode you can also infer it from the original. Keep code, file names, and identifiers in English.
Red line: no sentences about the reader in the document
Write only about the topic itself — not who the reader is, whether they get it, or whether they need to get it. Not one of the following sentence types may appear — in the body, the opening, subheadings, figure captions, or footnotes:
- “This explainer is written for people who don't write code.”
- “Aimed at non-technical readers / business colleagues / beginners / laypeople / outsiders”
- “You don't need to know any technology to follow this.”
- “In plain language / plain-language version / simplified version / layman's terms”
- “In short, all you need to remember is one sentence.”
Why: Sentences like these contribute zero to understanding the topic, yet they lower the document's positioning from “explaining a thing” to “catering to a group of people” — and readers feel patronized. The reader's background determines how you write, not what you write — it should show in the wording, not be declared.
What to do instead: make the first sentence of the opening a fact or conclusion about the topic itself.
- ✗ “This document introduces our message queue and is written for colleagues who don't write code.”
- ✓ “After an order is submitted, inventory is not deducted immediately — there is a queuing step in between, with an average wait of 200 milliseconds.”
Writing guidelines
- Give the conclusion first, then the mechanism. The first sentence of a section is the section's answer; everything after it is why the answer holds. No warm-up in the opening — the first line is the answer.
- One sentence, one idea; when writing operational steps, one sentence, one action.
- Active voice; make clear who did what. “The validation blocked this release,” not “This release was blocked.”
- Keep sentences short. A sentence that needs a breath halfway through was two sentences all along.
- One term, one meaning; one meaning, one term. Don't alternate names for the same thing — readers will think you mean different things.
- Use the present tense, unless time itself is the fact being told.
- Prefer lists to airless paragraphs — but a list doesn't excuse dropping the relationships between items; when sequence, causation, or dependency matters, write it down.
- Use terminology when it's called for, but give the meaning in one sentence at first appearance, right after the term — no apologies, no scare quotes signaling “this word is very technical.” If a term genuinely has no plain alternative, write what the reader will see and what they need to do, with the term itself appearing once in parentheses.
- Code, commands, and config entries are exact strings. Don't change a single character of anything the user must type or run; the explanation goes around it.
- Analogies serve precision, not friendliness. Keep an analogy only if it lets the reader make correct inferences in the next paragraph; don't turn the subject into a children's story to seem approachable.
- Don't omit the magnitudes the reader will rely on. How fast, how much, how costly, how high the failure rate — numbers beat adjectives.
- When something is uncertain, say it's uncertain; don't smooth it over with vague phrasing.
- Aim for no more than half the original length, unless “Restating hard rule 1” or the number of items the user names makes that impossible.
Document mode, first step: determine the type, then set the focus
With a document in hand, do two things before writing:
- Determine the type. Is this a PRD, development plan, technical proposal, review minutes, or an incident retrospective?
- Set the focus. Which questions must the reader be able to answer after reading? The focus determines what goes first and gets expanded, and what moves to the back and gets one line.
Rewriting is not rephrasing each paragraph of the original in turn. The original's outline follows the author's thinking (background, goals, approach, schedule, risks…); the new document follows the reader's questions. The two orders should not be the same in the first place.
PRD
The reader should be able to answer:
- What will be added? Write it as behavior the user can observe; don't write module names.
- What does the system look like when it's done? Where does it differ from today?
- How is implementation suggested? How many steps, in what order, and what's visible after each step.
Development plan
First look at the records in the plan to tell whether it's finished — checkboxes, status fields, progress-update sections, and revision history are all signals.
- Not finished: the focus is what will be developed and what the technical route is — which path was chosen, why that one, and what it costs.
- Finished: the focus is what was built, how the reader can verify it themselves (down to where to click, what command to run, which number to look at), and what's still missing or needs follow-up.
- Half finished: write both parts. First what's done and how to verify it, then what remains and the technical route. What counts as done follows the original's records.
If the plan says “completed” but this session didn't actually verify it, write “the plan records it as completed,” not “it is completed” — restating hard rule 3.
Other types
Ask the same question first — “what should the reader be able to answer after reading?” — then set the focus. If you can't determine the type, or can't tell whether the plan is finished, ask the user. Don't guess.
Focus is not an excuse to drop content
Focus decides order and level of detail, not what stays and what leaves. Restating hard rule 1 still applies: every warning, risk, number, and premise in the original must still appear in the new document — it can be moved back or squeezed into one line, but it cannot vanish.
Restating hard rules (when the input is a document)
- Only subtract; never gloss over. Every warning, risk, number, and precondition in the original must still be there after the rewrite. Dropping the “summary” from a ⚠ line is a lie. Anything involving security, data loss, or any action that's hard to undo must be written out in full — don't abbreviate.
- Numbers stay as they are. Amounts, quantities, and dates are not rounded. Ticket numbers and PR numbers that refer to a specific action are copied verbatim.
- As true as the original, not truer. What the original says remains a claim: write “the plan says all tests will pass,” not “all tests will pass” — unless you verified it yourself in this session.
- Keep unclear things unclear. Where the original is vague, write “the original does not say”; don't fill the gap by guessing.
Output format: a local HTML file
Default: write locally, don't publish. A single file with styles and scripts inline, no external network dependencies — double-click to open, and it can be sent as an attachment. Follow the user's specified path; if none is given, use the current directory (if the repo already has a
, put it in
). Name the file after the topic; in document mode follow the original document's name. When done, tell the user the path.
Switch to the Artifact tool for publishing only when the user explicitly says “publish / give me a link / use Artifact” (then load the
skill first).
This document is meant to be looked at, not read:
- A big diagram: the core process/structure is told in one full-width diagram, and the diagram stands alone (self-annotated, not dependent on the body).
- Key numbers as metric blocks: the value in large type, with one line beside it saying what it means ( followed by “users barely notice it”).
- Charts must have legends and axis labels; color is not the only distinguishing cue.
- Table headers carry explanations: every column name that might not be self-evident gets a tooltip ( or a hand-rolled tooltip) explaining what that column is really about.
- Readable on mobile; wide content scrolls horizontally inside itself, while the page itself never scrolls horizontally.
- In document mode, put the source (path or link) and the version you read at the end of the body, so readers can go back and cross-check. Don't put it at the beginning — the beginning belongs to the topic itself.
Pre-delivery self-check
- Read the whole thing; search for any sentence describing the reader's identity or level — if found, cut it. Don't rewrite it as a milder version; delete it outright.
- Is the first sentence a fact about the topic? If it's introducing this document, rewrite it.
- For every figure and every number: if it were removed, would the reader miss a conclusion? If not, it's decoration — delete it.
- Take a concrete question (“What happens when it fails?” “How much does it handle per day?”) and check whether the document answers it. If not, add it.
- Document mode: can the document answer each of the focus questions one by one? Add whatever it can't answer.
- Document mode: put the new document's subheadings side by side with the original's outline — if they match section for section in roughly the same order, you're only rephrasing paragraph by paragraph. Regroup by focus.
- Document mode, one more pass: can every warning, risk, number, and premise from the original be found in the new document? Put back whatever is missing.
Common pitfalls
- “I didn't understand” is feedback, not a challenge. Just explain it again. Don't defend yourself, don't re-explain at the same height, and don't smuggle “this is what I was thinking at the time” into the re-explanation.
- Re-explaining is not quietly fixing errors. If you discover during the re-explanation that what you wrote was wrong, that's a correction — say so plainly; don't silently swap it out in a “simpler version.”
- Interrupted mid-task with “wait, what does this mean?”: re-explain that spot first, then return to the original task. Don't drop the thread.
- The original was already clear: say “the original is already clear enough,” then stop. Inventing a different version just to look useful is padding.