言簡意賅 — words concise, meaning complete
言簡意賅 (yán jiǎn yì gāi) — "words few, meaning complete". The discipline of brevity-with-completeness: every sentence must be load-bearing; padding is the failure mode. The 90% case answerable from the first paragraph; the rest is reachable but not foregrounded.
This skill is sibling to chengyu-great-wisdom-looks-foolish; the failure modes are orthogonal:
| Skill | Failure mode | Example |
|---|---|---|
| 大智若愚 (great-wisdom-looks-foolish) | Performative CLEVERNESS — over-engineered solutions, rare vocabulary | Building a factory for what should be a function |
| 言簡意賅 (words-concise-meaning-complete) | Performative SPRAWL — over-verbose output, unnecessary padding | 3 paragraphs to say what a sentence would |
Both push toward unornamented output, but through different mechanisms. Invoke either or both.
The TLDR-outside / details-inside pattern
The cleanest expression of this skill — broadly applicable but most explicit on GitHub:
When a comment / PR description / issue body has any longwinded content (tables, code blocks, range-diffs, multi-point walkthroughs), it should open with a TL;DR and put the rest inside a
<details>collapsible.Reviewers skim. A wall of text raises the cost of "what did this say?" — the TL;DR pays the bill in one line. The collapsible keeps the proof reachable for whoever wants to drill in, without cluttering the timeline.
This is the GitHub-comment-specific application. The general principle: load-bearing content goes first, supporting content is reachable but not foregrounded. Applies anywhere — agent reply, PR description, doc, design summary, post-mortem.
When this applies
Symptoms that this skill applies:
- About to write a multi-paragraph explanation when one sentence answers the question
- About to use 3 hedges where 0 would do
- About to include "interesting context" that isn't load-bearing for the user's decision
- A test file is verbose with try-finally / setup-teardown / context-manager when none is needed
- A code comment is "too long" — comments accumulate sediment over revisions; a multi-line block usually has one load-bearing line and N lines of decoration
- A GitHub comment / PR description / issue body has tables, code blocks, range-diffs, or multi-point walkthroughs — the TL;DR-outside / details-inside pattern fires
- A filename / identifier is verbose when a short one would do
Behavior
- Identify the load-bearing content — the one or two sentences the user's next action depends on. That goes first.
- Compress everything else. Reachable but not foregrounded. In writing:
<details>. In code: separate function. In speech: parenthetical. In docs: appendix. - Skip the ceremony. No "I'd love to help with this!" preamble. No "I hope this helps!" closing. No paragraph of context-setting before the actual answer.
- Distinguish brevity from terseness. Brevity = no padding. Terseness = no scaffolding. Brevity is the goal; terseness can sacrifice completeness.
- For GitHub comments specifically: TL;DR sentence +
<details><summary>label</summary> ... </details>. The summary should hint at the form, not the conclusion (Per-point status table,What changed and proof,Range-diff output, etc.).
Anti-pattern
Padding to look thorough. Length as performance. Recall test: "what did this actually say?" If the answer is ≤ one sentence, the rest was padding.
Brevity through omission of load-bearing content. The chengyu is brevity-with-completeness. Cutting the load-bearing detail in pursuit of shortness is just incomplete, not concise.
Terseness without scaffolding. A one-liner that requires three Stack Overflow tabs to parse is not 言簡意賅 — it's compression without communication. The user should be able to act on the brief version without external lookup.
Skipping TL;DR when it's required. GitHub long comments without TL;DR cost reviewers. Reviewer bandwidth is finite; padding the comment shifts cost to them.
Applying brevity uniformly. Sometimes the user needs depth (a design spec, a post-mortem, a primer). Brevity is the default, not the only mode. The skill is invoked, not always-on.
Relationship to other skills
- chengyu-great-wisdom-looks-foolish — orthogonal-but-paired representation discipline. 大智若愚 cuts cleverness; 言簡意賅 cuts sprawl. Often invoked together.
- chengyu-teach-by-material — format-calibration. Sometimes the right answer to verbosity is not just "shorter text" but "different format" (HTML dashboard for multi-item; PPTX for walk-through; markdown file for reference). 言簡意賅 inside the chosen format; 因材施教 picks the format.
Etymology
A classical four-character chengyu of literary criticism. Used for centuries to describe writing that achieves complete meaning with minimal words — the ideal of every form from regulated verse to imperial memorial.
The chengyu's whole structure embodies its principle: four characters, no padding, complete meaning. 言 (words) + 簡 (few/concise) + 意 (meaning) + 賅 (complete/comprehensive). Removing any one breaks the principle; adding any would falsify it.