tldr · diff
v1.1 to v1.2
22 added, 8 removed. Audit A to A.
---
name: tldr
category: communication
activation: command
disable-model-invocation: true
environments: coding, chat
argument-hint: "[file | PR | URL | topic — empty means the last message]"
- description: Compressing something long into the few facts needed to decide or act — the last message and the work behind it, or a named file, PR, document, or thread.
+ description: Compressing something too long to read into the few facts needed to decide or act, read instead of the source — the last message and the work behind it, or a named file, PR, document, or thread.
metadata:
- version: "1.1"
+ version: "1.2"
---
# TL;DR
- Something got too long to hold. Hand back the **cliffs**: the few facts that let
- the user decide or act, and an honest line about what those facts leave out.
+ Something got too long to read. The user calls this instead of reading it, so
+ hand back the **cliffs**: the few facts that let them decide or act, and an
+ honest line about what those facts leave out.
Cliffs, not a **telegram**. A telegram is shorter and just as unusable — it
drops the premises, so only someone who already read the source can parse it.
The cliffs let someone who read nothing hold their own in the conversation.
## What to summarize
| Argument | Target |
|---|---|
| *(none)* | The last assistant message **and the work behind it** — the tool calls, files, and findings it was reporting on. |
| A path | That file or directory. |
| A PR, issue, branch, or diff | The change: what it does, what it breaks, what a reviewer must look at. |
| A URL or attached document | That document. |
| A topic in prose | The part of this session about that topic. |
Read the target in full first. Cliffs assembled from a diff stat, a file
listing, or a page title are a guess wearing a summary's clothes.
When the argument reads two ways — a word that is both a filename and a
topic — resolve it from what the user has been doing and name the reading you
picked in one clause. Answer rather than ask.
## The shape
```markdown
**Bottom line.** [One sentence. What survives if they read nothing else.]
- [Load-bearing fact]
- [Load-bearing fact]
- [3–5, ordered by what the decision turns on, not by source order]
**Your move.** [The decision waiting on them, the next step, or "nothing — FYI".]
**Left out:** [What was cut that could still matter, or "nothing that changes the above".]
```
The shape is the length budget; there is no word count to hit.
The same thread as a telegram, its source, and its cliffs:
Telegram: `Auth → gateway. Cache unchanged. New secret. LGTM w/ nit.`
Source:
```markdown
Mara: gateway migration ships Friday, I own the rollout.
Luis: rate limiting is untested, keep it out of this PR.
Mara: agreed, rate limiting waits; `GATEWAY_JWT_KEY` must exist first.
```
Cliffs:
```markdown
**Bottom line.** Mergeable once the secret exists; rate-limit timing is settled.
- Auth checks move to the gateway; Mara owns the Friday rollout.
- Deploy fails without `GATEWAY_JWT_KEY` in staging and prod.
- Rate limiting ships next week (inferred — agreed as follow-up, no date given).
**Your move.** Create `GATEWAY_JWT_KEY`, then confirm Friday with Mara.
**Left out:** the caching refactor (no behavior change) and three naming nits.
```
The telegram only parses for someone who already read the PR; the cliffs
carry the premises (*what* moved, *why* deploy fails) and keep the
disagreement as two positions.
## Load-bearing
A fact is **load-bearing** when removing it changes what the user does next.
Load-bearing detail survives verbatim: numbers, versions, paths, identifiers,
error strings, names, owners, deadlines, decisions taken. Adjectives,
transitions, restatements, and the order the source happened to use are what
compression eats.
Three things stay load-bearing however long the source is:
- **Claims, not topics.** "Covers auth, caching, and deploy" is a table of
contents. Say what it *says*: "auth moves to the gateway, caching is
unchanged, deploy needs a new secret."
- **The disagreement.** An unresolved thread or two conflicting sources stay two
positions in the cliffs. Collapsing them into one confident answer is the most
expensive error this skill can make.
- **The gaps.** "I could not read section 4" and "section 4 does not matter" are
different sentences; write the true one. Mark inference as inference:
"(inferred — the doc never says)".
+ ## Plain on first read
+
+ The user did not read the source, so the cliffs get one pass and no premises
+ from it. Write them so that one pass is enough:
+
+ - Context first: the bottom line says where things stand and why it matters
+ before it says what follows.
+ - Short sentences in the active voice, one thought each.
+ - One word, one meaning: name the same thing the same way every time.
+
Prose follows the conversation, terms follow the source. The cliffs are written
in the language the chat is in — an English PR summarised into a German thread
comes back German. What stays in the source's own words are the terms
themselves: identifiers, error strings, and a repo's `GLOSSARY.md` ubiquitous
- language. Translating those, or inventing a cleaner label, makes the reader
- translate back.
+ language (with several glossaries, `GLOSSARY-MAP.md` names the right one).
+ Translating those, or inventing a cleaner label, makes the reader translate
+ back.
## When it is a different ask
- **Writing a status from activity or for an outside audience.** A standup
drafted from recent activity is a `repo-status` task (suggest the user run
the command); a status for readers outside the working group is
`stakeholder-update`.
- - **Short, and it still did not land.** The gap is missing premises. Back up and
- re-explain with them. In a German chat, suggest the user run `was`, which
+ - **Short, read, and it still did not land.** Length decides, and it is
+ visible before reading: long and unread comes here, short but unclear after
+ reading does not, because the gap is missing premises and shortening adds
+ none. Back up and re-explain with them, or suggest the user run `was`, which
re-pitches the last message in plain German.
- **The reasoning is the point** — a trade-off, a review call. Give the shape of
the argument: both positions and what each turns on.
- **Already short, no core, or a summary just written.** Say that in one line;
a thinner copy helps nobody.
## Before sending
Point each bullet at its source line or passage. A bullet with no source
goes out or goes marked "(inferred)".
## Done when
The user could act on the cliffs without opening the source, every bullet
changes what they would do, and every number, path, and name in them was copied
rather than remembered.