Plain Speak

English · 中文 · 日本語

A Claude Code output style for people who ship with AI but make every technical call themselves — plus the tooling to derive your own version of it from your own conversation history.

---

The problem it actually solves

The obvious theory is "the AI uses too much jargon." That theory is wrong.

This style was derived by mining a multi-month Claude Code history: every time the human replied "what does that mean?", the assistant message immediately before it was captured as a failure sample; every time they replied "ok, go ahead", the message before it was captured as a success sample. Then the two piles were compared mechanically.

The result was counterintuitive:

	Answers that confused them	Answers they approved
Density of code identifiers	lower	higher
Contained a "here's what you need to decide" list	very common	rare
Density of commit hashes in the opening	~10× higher	near zero
Density of words like user / page / screen	lower	higher

Jargon was never the variable. The decision moment was. The answers that failed were the ones that asked the human to make a call — while withholding what they needed to make it: how things got here, what the whole chain actually does, who runs into it, and what happens if nothing changes.

And follow-up questions clustered in the final quarter of an answer — not because endings are special, but because that's where the assistant compressed things it had decided were unimportant.

So this style spends almost none of its rules on vocabulary. It spends them on:

• Decision items — each one is a paragraph carrying who hits it → what happens → cost of doing nothing → options and a recommendation, never a one-line bullet pointing at a line number.
• Starting state — before asking for a call, say how things stood, what happened, and where they are now. An analogy can't substitute for this.
• Mental model before detail — reach for one everyday analogy when a mechanism won't form a picture, then reuse it throughout.
• Relaying sub-agent results — an external model's findings don't exist until you actually say what they were.
• One word, one referent — the most dangerous failure isn't "I don't understand," it's confidently understanding the wrong thing.

Install

Drop the style file into your output styles directory and select it.

# user-level (all projects)
mkdir -p ~/.claude/output-styles
curl -o ~/.claude/output-styles/plain-speak.md \
  https://raw.githubusercontent.com/Marksooxx/plain-speak/main/styles/plain-speak.en.md

# or project-level
mkdir -p .claude/output-styles && cp styles/plain-speak.en.md .claude/output-styles/

Then in Claude Code: /config → Output style → pick it → /clear (the style is read once at session start).

To set it without the menu, add to ~/.claude/settings.json:

{ "outputStyle": "Plain Speak" }

The value is the name: from the file's frontmatter, not the filename. A wrong value silently falls back to default. A project-level .claude/settings.local.json overrides the user-level one — if a project has its own outputStyle, set it there too.

Language versions carry different name: values, so you can install more than one and switch:

File	name:
styles/plain-speak.en.md	Plain Speak
styles/plain-speak.zh-CN.md	说人话
styles/plain-speak.ja.md	平たく話す

Make your own version

Don't take my rules on faith. The style file has a ## Who is reading section that is meant to be replaced — and the rules themselves should be argued from your evidence, not mine.

python3 tools/mine_feedback.py

It reads ~/.claude/projects/*/*.jsonl (your local transcripts — nothing is uploaded anywhere) and writes:

• out/negative.json — every time you signaled confusion, paired with what the assistant had just written
• out/positive.json — every time you approved, paired with the same
• out/digest.md — a readable walkthrough of the failures

python3 tools/mine_feedback.py --project ~/.claude/projects/<slug> --lang en
python3 tools/mine_feedback.py --lang zh,ja --out ./mine

Confusion signals ship for zh, en, and ja; extend the CONFUSION / APPROVAL dicts at the top of the script for your own phrasing.

Then read digest.md and ask one question of every sample: what rule would have stopped this from being written? Those rules are your style file. The ones in here are just the ones that came out of one particular history.

A note on length

This file is longer than the built-in output styles, on purpose — but length is not the goal, and the file says so about itself. Two things worth knowing:

1. Custom output styles get no per-turn reminder. Built-in styles (Explanatory, Learning, Proactive) are re-announced to the model every turn; custom ones are injected once at session start. Long files drift. Keep yours as short as the evidence allows.
2. Don't cut by word count, cut by priority. The style includes an explicit precedence order: when length gets tight, drop stat dumps, repeated definitions, analogies, and Insight blocks — never the facts, consequences, or options that would change a decision.

Credits

Derived from real Claude Code usage, then cross-examined by a multi-agent review and an independent model, which between them killed roughly twenty self-contradictions and over-absolute rules. The surviving rules are the ones that had evidence behind them.

License

MIT — see LICENSE.