skills/skills/think-twice/SKILL.md

---
name: think-twice
description: >
  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](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.