im0o
f0c4002c89
对应源仓 think-twice 的 d80e546。副本内容与源仓一致。 SKILL.md:blocker 五项改为显式有序;读者表格不再按"top-left cell"这类位置引用; style.md 的加载条件(含 code-heavy 跳过那个例外)从 style.md 搬进 SKILL.md 正文。 style.md:删掉开头写给维护者的说明,只留用途和用法。
8.1 KiB
name, description
| name | description |
|---|---|
| think-twice | Rebuild an outgoing text so a reader holding only it can understand or act, with every claim verified and nothing left in it that only mattered along the way. Use when the user says they do not understand, asks to expand / explain / rewrite plainly / make it self-contained; when shipping prose that must stand alone (handoff, PR or issue body, doc, subagent brief, summary of a system); or when another skill needs a clarity or evidence pass. |
Think Twice
Do not polish the last draft. Rebuild it from only what will appear in the text you send.
Three questions decide every rule below. A rule that answers none of them does not belong here, however good the writing advice.
- Can they parse it? The reader hits a word or a pointer they cannot resolve, and the paragraph stops.
- Is it true? They read it, act on it, and reality does not match.
- How much of it survives? They open it a week later and have to wade through what only mattered while it was being written.
A text can pass one and fail the others. Verification comes first: fluent invention does more damage than clumsy truth.
One case skips the whole process: a throwaway one-line instruction the user has already acted on, or already knew. Do not rewrite it and do not verify it.
The reader
Two axes, and using only one of them is the common failure. Access is what they can open right now. Background is what they already know.
| knows the domain | does not | |
|---|---|---|
| can open the code | exact locations, code, schema | the design one level up; code as an optional anchor |
| cannot | conclusion and boundaries | consequences and comparisons |
The table is a default, not a verdict. A reader who can open the code and knows the domain may still be optimising for speed and want the design level with no code at all. When it is unclear, one direct question is faster than a guess.
Pitch one level higher than feels natural and let them ask downward. Opening with code or a schema is a choice that needs a reason: they asked for it, or they have quoted it themselves.
The cold reader holds this text plus whatever is guaranteed in front of them at the moment they read it, and nothing else. Assume that moment is a week from now and the conversation is gone. An LLM cold reader is worse off than a human: it does not error on an undefined reference, it silently invents a plausible meaning for it.
Process
1. Locate the blocker
The five blockers run from highest to lowest; pick the highest that applies. level (pitched at the wrong altitude), concept, scope, steps, token (undefined word or dangling pointer). Then name which conclusion, boundary, evidence and next step this text must carry.
Done when: one blocker is named and every load-bearing slot is listed.
2. Fill, then verify
Two jobs, and the second does not cover the first.
Fill — go find the facts that belong in the text and are not in the draft yet. A draft that never mentions a thing raises no alarm on its own, so nothing downstream will catch the omission.
Verify — every claim already drafted gets checked against its source: read the file, run the command, open the page. Where verification is impossible from here, write what is unknown and what would resolve it.
Done when: no load-bearing fact is missing, guessed, or unlabeled.
3. Rebuild, do not patch
Order: conclusion, then what it is in plain observable terms, then in and out of scope where partial work could be misread, then evidence where trust matters, then the minimal path where action matters, including the success shape and the next move on failure.
Done when: every line obeys the rules below.
4. Deliver
Conclusion first, always. Short is the default for a person reading in chat.
Go long only when the artifact itself is long-form (a handoff, a PR or issue body, a doc), or the user asked for detail, or the load-bearing facts do not fit without changing meaning. When it has to be long, put the body in a file and keep the chat message short.
Done when: a reader holding only this can say what it means, how far it goes, and what to do next, wherever those questions matter.
Rules
Can they parse it
- No dangling references. Undefined unless the body supplies them: "as discussed", "per the design", "as usual", "as you mentioned", "see above". Same for a private path or id used as the only source of a required fact. Restate the fact, or give a locator and what to take from it.
- Gloss on first use. Acronyms, nicknames, codenames, internal shorthand: one clause, at the first appearance, nowhere else.
- One term, one meaning. A thing keeps its name for the whole text; a synonym halfway through reads as a second thing.
- Mechanism, then name. What they can see or do comes first; the internal label second.
- Define before you label. Why it matters, what it does and does not do, then the name for it.
- Pin partial work. What this does, what it deliberately does not, and whether the larger goal is finished or only advanced.
- Quote in the original, gloss in the reader's language. A verbatim quote is evidence; an untranslated one is a wall.
Is it true
- Verified or labeled. Evidence you actually checked, or an explicit "unverified". Never a guess in a conclusion's voice.
- Evidence is concrete. The file and line, the command and its real output, the exact quote. "I checked" is not evidence.
- Quotes carry attribution. A decision, constraint or priority is quoted verbatim, in its original wording, with who said it and when. A paraphrase presented as fact turns a reversible decision into a law of physics.
- Fact and judgement stay visibly apart. A verifiable fact gets checked. Someone's decision gets attributed.
- Predict, then look. Write the expected result before reading the actual one. Matching afterwards is back-fitting, and the output would have "confirmed" whatever you wrote.
- Work already run is evidence. Copy its real output instead of re-running, which can repeat side effects. Predict-then-look still applies to it.
How much survives
- Cut the path you took. The reader needs the decision and the shortest route to it, not the dead ends. Evidence attaches to a claim; it is never narrated as history. Test: if a sentence needs "first, then, and it turned out" to stand up, it is process, so cut it.
- Say what it is, not what it is not. A negation earns its place only if the reader would arrive at that wrong idea on their own. "This script does not delete files" is a boundary and stays. "Not used as an SSH jump host", written only because someone in the conversation had guessed wrong, is a correction scar and goes. Delete the sentence and check whether the misreading comes back.
- Date everything that moves. Absolute dates, never "last week". Drop "now", "currently" and "just", or pin the moment they refer to. A pointer to something that changes, such as a branch head or a running process, is marked as a snapshot.
- Drop whatever does not change understanding or action.
- No appendix for safety. Length is not thoroughness.
Chinese prose for a human reader
When the output is Chinese prose a person will read, and it is not code-heavy, also load style.md and sweep its list before delivery. It is the only conditional part of this skill.
When the rewrite misses
They still do not get it, or ask the same thing in different words. Diagnose level before anything else: the usual cause is prose pitched below the reader, and the fix is one re-aim higher, not a handover. A miss that survives that goes to the teach-me skill, which needs a reader who can talk back. Never a third rewrite.
Boundary
This skill governs the words. Tracker links, close keywords and PR mechanics belong to whatever process owns them.