adhd-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

adhd-md

把 Markdown 改造成 ADHD 友好的样子：结论前置、段落切碎、句子变短、动作明确、噪音归零。

铁律：只重排信息，绝不删信息。 篇幅太长就折叠或移到附录，不许删。违反这条，其他做得再好都是失败。

Transform Markdown into an ADHD-friendly format: lead with conclusions, break up paragraphs, shorten sentences, use clear actions, and eliminate noise.

Golden Rule: Only rearrange information, never delete it. If the content is too long, fold it or move it to an appendix—do NOT delete it. Violating this rule means failure no matter how well other tasks are done.

什么时候用

When to Use

用户给了一个 Markdown 文件（或一段 Markdown），希望它更好读、更好扫、更适合注意力容易断的人。

不适用的情况：

输入不是 Markdown（先转换，或直接拒绝）
用户要的是内容审查（事实核查、逻辑校对）—— 那不是这个 skill
用户要的是翻译或扩写 —— 都不是

Use this when the user provides a Markdown file (or a snippet of Markdown) and wants it to be more readable, skimmable, and suitable for people with easily distracted attention.

Unsuitable scenarios:

Input is not Markdown (convert first, or reject directly)
The user requests content review (fact-checking, logic proofreading) — this is not the purpose of this skill
The user requests translation or expansion — neither is within scope

两个参数

Two Parameters

scope：改什么

scope: What to Modify

值	边界	用户会怎么说
`format`	正文词序列逐字不变，只动标记、空白、块顺序	只改格式 / 只调样式 / 别动我的字 / 排版优化
`content`	只改措辞与信息组织，不碰排版风格	只改内容 / 句子太长 / 帮我改写
`both` （默认）	全都改	优化一下 / 改成 ADHD 友好

划线判据：搬移已有块算 format，写出新句子算 content。

把结论段整块搬到开头 = format。新写一段 TL;DR = content。

Value	Boundaries	User Phrases
`format`	The word sequence of the body text remains exactly the same; only modify markers, whitespace, and block order	"只改格式" / "只调样式" / "别动我的字" / "排版优化"
`content`	Only modify wording and information organization; do not change layout style	"只改内容" / "句子太长" / "帮我改写"
`both` (default)	Modify both	"优化一下" / "改成 ADHD 友好"

Judgment Criterion: Moving existing blocks counts as format modification; writing new sentences counts as content modification.

Moving an entire conclusion block to the beginning = format. Writing a new TL;DR section = content.

level：改多狠

level: How Extensive the Modifications Are

值	适用	会做什么
`light`	规范、合同、API 文档，怕动	只做零风险项，不重排顺序
`standard` （默认）	README、教程、设计文档	拆段、列表化、改标题、写 TL;DR、块重排
`deep`	会议记录、长文、堆积的笔记	全量重构骨架、渐进披露、生成 checklist

用户没说就用

both

standard

，并在报告开头一句话说明用了什么档，让人能反悔。

Value	Applicable Scenarios	Actions Taken
`light`	Specifications, contracts, API docs where changes are risky	Only perform zero-risk adjustments; do not reorder content
`standard` (default)	READMEs, tutorials, design docs	Split paragraphs, convert to lists, revise headings, write TL;DR, reorder blocks
`deep`	Meeting minutes, long articles, accumulated notes	Full skeleton restructuring, progressive disclosure, generate checklists

If the user doesn't specify, use

both

standard

, and state this clearly at the start of the report so the user can revise the choice.

工作流

Workflow

第 0 步 · 决定写哪里

Step 0 · Decide Where to Write

bash

git -C <文档所在仓库> status --porcelain <文件>

仓库干净 → 原地改，用户用
```
git diff
```
审阅
有未提交改动，或不在 git 里 → 写到
```
<原名>.adhd.md
```
，并告诉用户为什么

绝不在有未提交改动的文件上原地覆盖。

bash

git -C <repo-containing-document> status --porcelain <file>

Clean repo → Modify in-place, user reviews with
```
git diff
```
Uncommitted changes, or not in git → Write to
```
<original-name>.adhd.md
```
and explain why to the user

Never overwrite files with uncommitted changes in-place.

第 1 步 · 审计

Step 1 · Audit

bash

python3 <skill>/scripts/adhd_md.py audit 文件.md --level 2

拿到脚本分、逐条 findings（带

文件:行

）、以及需要你判断的规则清单。

先读输出再动手。 不要凭印象改 —— 脚本已经把能算准的都算了。

bash

python3 <skill>/scripts/adhd_md.py audit file.md --level 2

Obtain the script score, itemized findings (with

file:line

), and a list of rules requiring your judgment.

Read the output before making changes. Don't modify based on memory — the script has already calculated all quantifiable items.

第 2 步 · 确定性格式修复

Step 2 · Fix Formatting Automatically

bash

python3 <skill>/scripts/adhd_md.py fmt --write 文件.md

零风险、不需要你判断：行尾空白、有序列表序号、块间空行、中英文间距、中文标点。

scope=content

时跳过这一步。

可选开关：

--toc

（按已有标题生成目录）、

--join-cjk

（合并中文软换行）、

--strip-emoji

（删 emoji，注意这会改动字符）。

bash

python3 <skill>/scripts/adhd_md.py fmt --write file.md

Zero-risk, judgment-free fixes: trailing whitespace, ordered list numbering, blank lines between blocks, spacing between Chinese and English text, Chinese punctuation.

Skip this step when

scope=content

Optional flags:

--toc

(generate table of contents from existing headings),

--join-cjk

(merge soft line breaks in Chinese text),

--strip-emoji

(remove emojis, note this changes characters).

第 3 步 · 你来改

Step 3 · Manual Modifications

读

references/rules.md

，按 scope 过滤出生效的规则子集，逐条改。

顺序：先 content 再 format。措辞定了，排版决策才稳。

改之前必读：

```
references/rules.md
```
—— 规则全表，含阈值
```
references/antipatterns.md
```
—— 八种过度优化，这个必读
```
references/cjk.md
```
—— 文档是中文时读
```
references/doc-types.md
```
—— 只在
```
level=deep
```
需要重排骨架时读

Read

references/rules.md

, filter the applicable rule subset based on scope, and modify item by item.

Order: Content first, then format. Only after wording is finalized can layout decisions be stable.

Must read before modifying:

```
references/rules.md
```
— complete rule list, including thresholds
```
references/antipatterns.md
```
— eight over-optimization patterns, mandatory reading
```
references/cjk.md
```
— read if the document is in Chinese
```
references/doc-types.md
```
— read only when
```
level=deep
```
and skeleton restructuring is needed

第 4 步 · 校验

Step 4 · Verification

bash

python3 <skill>/scripts/adhd_md.py verify 原文.md 新文.md --scope=format
python3 <skill>/scripts/adhd_md.py report 原文.md 新文.md --scope=<scope>

scope=format

时 verify 是硬门禁：token 序列必须完全一致。不通过就回退，不许放行。

scope=content

或

both

时 verify 检查不变量：代码块、行内代码、URL、标识符、数字。任何硬失败都要修到通过。

原地改时先留一份原文到临时文件，否则没法 verify：

bash

cp 文件.md /tmp/adhd-orig.md   # 改之前

bash

python3 <skill>/scripts/adhd_md.py verify original.md new.md --scope=format
python3 <skill>/scripts/adhd_md.py report original.md new.md --scope=<scope>

When

scope=format

, verification is a hard gate: the token sequence must be identical. If it fails, roll back changes — do not proceed.

When

scope=content

both

, verification checks invariants: code blocks, inline code, URLs, identifiers, numbers. Fix any hard failures until verification passes.

When modifying in-place, save a copy of the original file to a temporary location first, otherwise verification is impossible:

bash

cp file.md /tmp/adhd-orig.md   # before modification

第 5 步 · 报告

Step 5 · Report

必须包含四项：

用了什么 scope 与 level
脚本分 before → after，逐维度 delta
verify 结论（通过 / 失败及原因）
你改了什么、以及故意没改什么

反模式扣分（X 组）after 必须为 0。不为 0 说明你是靠过度格式化换分数，回退重来。

AI 味（M 组）命中数只许下降，不许上升。 你改写内容时最容易顺手写出「不是 A 而是 B」「值得注意的是」，等于用一套问题换掉另一套。改完对比

audit

的活人感维度。

Must include four items:

The scope and level used
Script score before → after, with delta for each dimension
Verification result (Pass/Fail and reason)
What you modified, and what you intentionally did not modify

The anti-pattern (Group X) score must be 0 after modification. If not, it means you traded over-formatting for score — roll back and start over.

The number of AI-style (Group M) hits must decrease, not increase. When rewriting content, it's easy to accidentally write phrases like "not A but B" or "it is worth noting that", replacing one problem with another. Compare the human-centric dimension from the

audit

result after modification.

三种 scope 的 do / don't

Do / Don't for Three Scopes

scope=format

能做：在已有句界拆段 · 并列句转列表（复用原词）· 加粗已有关键术语 · 补空行分割线 · 代码块补语言标签 · 标题层级修正 · 列表降嵌套 ·

<details>

折叠（summary 复用已有标题文字）· 由已有标题生成 TOC · 块顺序重排 · 中英文间距与标点规范

不能做：改任何一个词 · 新写 TL;DR · 改写标题措辞 · 补时间预估 · 补下一步动作 · 删填充词

块重排的陷阱：把结论块搬到开头后，扫一遍被搬走的块里有没有「这个方案」「上述配置」「它」这类悬空指代。修指代要改词，属于 content —— 所以

scope=format

下检出悬空指代时，放弃这次搬移，在报告里记「需 content 权限才能安全前置」。

Allowed: Split paragraphs at existing sentence boundaries · Convert parallel sentences to lists (reuse original words) · Bold existing key terms · Add blank lines/dividers · Add language labels to code blocks · Fix heading hierarchy · Reduce list nesting · Fold content with

<details>

(reuse existing heading text for summary) · Generate TOC from existing headings · Reorder blocks · Standardize spacing between Chinese/English and punctuation

Not Allowed: Modify any words · Write new TL;DR · Rewrite heading wording · Add time estimates · Add next steps · Delete filler words

Trap in block reordering: After moving a conclusion block to the beginning, check if the moved block contains dangling references like "this solution", "the above configuration", or "it". Fixing references requires modifying words, which falls under content — so when dangling references are detected with

scope=format

, abandon the move and note in the report: "Content permission required to safely frontload this section".

scope=content

能做：长句拆短 · 被动改主动 · 结论前置改写 · 新写 TL;DR · 标题改成结论式 · 补时间预估与下一步 · 术语首现解释 · 删填充词与虚词壳 · 拆括号插入语 · 消灭「如上所述」· 洗掉 AI 味（翻案腔、预告式冒号、装深刻的话、黑话、名词化）

不能做：改排版风格（不新增标题层级、不改列表形态、不动折叠结构）· 也不能借「精简」之名删约束条件、单位、版本号、例外情况

Allowed: Split long sentences · Convert passive voice to active · Rewrite to lead with conclusions · Write new TL;DR · Revise headings to be conclusion-based · Add time estimates and next steps · Explain terms on first occurrence · Delete filler words and empty phrases · Split parenthetical insertions · Eliminate phrases like "as mentioned above" · Remove AI-style phrasing (contradictory tone, predictive colons, pretentious language, jargon, nominalization)

Not Allowed: Change layout style (do not add new heading levels, modify list types, or adjust folding structures) · Do not delete constraints, units, version numbers, or exceptions in the name of "streamlining"

scope=both

先 content 再 format，最后统一 verify。默认档。

Process content first, then format, and perform unified verification at the end. This is the default setting.

没有 shell 的宿主怎么办

What to Do Without Shell Access

拿不到 Bash / 命令执行时：

跳过 audit / fmt / verify，按
```
references/rules.md
```
人工过一遍
用
```
references/antipatterns.md
```
末尾的自检清单逐条自查
在报告里明确写「未做机器校验」 —— 不许假装跑过脚本

假装跑过校验，比不校验更糟。

If Bash / command execution is unavailable:

Skip audit / fmt / verify, manually review according to
```
references/rules.md
```
Use the self-check checklist at the end of
```
references/antipatterns.md
```
to check item by item
Clearly state "No machine verification performed" in the report — never pretend to have run the scripts

Pretending to have run verification is worse than not doing it at all.

输出契约

Output Contract

改完给用户的报告，照这个格式：

markdown

undefined

Follow this format for the report provided to the user:

markdown

undefined

改完了：<文件名>

Done: <filename>

scope

both

· level

standard

· 写到

原地

（git 干净）

脚本分 62.4 → 88.1（+25.7）

维度	before	after
首屏结论力	40	100
……

verify(both) 通过 —— 代码块、URL、标识符、数字全部保全

改了什么

把最后一段的结论整块搬到开头（format）
12 个超长句拆成 28 句（content）
3 处「如上所述」就地重述（content）

故意没改

```
## API 参数
```
一节保持原样：参考类内容需要跳读，重排会破坏定位
两处 92 字长句保留：拆开会切断因果关系


「故意没改」这一节不许省。它让用户知道你是判断过的，不是漏了。

scope

both

· level

standard

· Modified in-place (git repo clean)

Script score: 62.4 → 88.1 (+25.7)

Dimension	Before	After
First-screen conclusion effectiveness	40	100
……

verify(both) Passed — all code blocks, URLs, identifiers, and numbers are preserved

Modifications Made

Moved the entire conclusion block from the end to the beginning (format)
Split 12 overly long sentences into 28 sentences (content)
Rewrote 3 instances of "如上所述" in-place (content)

Intentional Omissions

Kept the
```
## API Parameters
```
section unchanged: reference content requires jump navigation, reordering would disrupt positioning
Retained two 92-word long sentences: splitting would break causal relationships


The "Intentional Omissions" section cannot be omitted. It lets the user know you made informed judgments, not missed items.

参考文件索引

Reference File Index

文件	什么时候读
`references/rules.md`	每次都读。规则全表 + 阈值 + 轴/档标记
`references/antipatterns.md`	每次都读。八种过度优化 + 自检清单
`references/rubric.md`	需要解释分数、或要手工补 judge 项评分时
`references/cjk.md`	文档是中文
`references/doc-types.md`	`level=deep` 且要重排整体骨架

File	When to Read
`references/rules.md`	Read every time. Complete rule list + thresholds + axis/setting markers
`references/antipatterns.md`	Read every time. Eight over-optimization patterns + self-check checklist
`references/rubric.md`	When explaining scores or manually supplementing judge item scores
`references/cjk.md`	When the document is in Chinese
`references/doc-types.md`	When `level=deep` and overall skeleton restructuring is needed

常见错误

Common Mistakes

错误	后果
把脚本分说成最终分	33 条规则按满分计入，虚高。必须说明这是脚本分
`scope=format` 却改了词	verify 硬失败。回退
以「精简」为名删内容	违反铁律。折叠或移附录，不删
改写时写出「不是 A 而是 B」	M1 翻案腔。直接从正面下判断
加 emoji 当锚点	X1 扣分。用 `> 注意` 、表格、分割线
切成一堆两行小节	X2 碎片化扣分
列表项砍成关键词	X3 剩词不剩句扣分
说跑了校验其实没跑	诚信问题，比不校验严重

Mistake	Consequence
Presenting the script score as the final score	33 rules are counted as full marks, leading to inflated scores. Must clarify it is a script score
Modifying words when `scope=format`	Verification fails hard. Roll back changes
Deleting content in the name of "streamlining"	Violates the golden rule. Fold or move to appendix instead of deleting
Writing "not A but B" when rewriting	Triggers M1 contradictory tone. Make direct positive judgments instead
Using emojis as anchors	Results in X1 deduction. Use `> Note` , tables, or dividers instead
Splitting into numerous two-line sections	Results in X2 fragmentation deduction
Reducing list items to keywords	Results in X3 deduction for incomplete sentences
Falsifying verification results	Integrity issue, more serious than not performing verification