It governs where information lands in the document, not the prose style.
There are only five principles here: no criteria, no thresholds, no severity levels. When reviewing a document, use these five tojudge, and state clearly that this is judgment rather than detection—problems of content organization cannot be determined mechanically.
This skill only judges and explains; it does not perform modifications. If the document is revised accordingly, the changes are limited to three kinds: moving things, adding definitions, deleting duplicate copies; any "improvement" that requires rewriting sentences to achieve falls outside the scope of this article.
Language
- Accepts questions in Chinese and English, replies uniformly in Chinese, and uses Chinese for documents
1. The body should contain only the current state; change history goes elsewhere
The harm is not difficulty in reading, but the loss of certainty about the current state.
When history and the current state are mixed in the same place, readers cannot tell which sentence is live. A document whose introduction contains two revision records while the body still keeps the old statements they overturned is effectively giving two answers to "what the current design is."
How to do it: Put change rationale into the change log / ADR section, and keep only the current conclusion in the document introduction.
Two things not to do：
- Do not move all change rationale to the end of the document—that moves the rationale away from the object it explains and creates another kind of fragmentation. The correct placement is to merge it into the section covering that content, or into an existing decision record entry
- Do not expect git to bear this responsibility—reasoning such as "why the initial proposal was rejected" cannot be read from a diff
When one revision affects multiple sections: Keep one complete, atomic decision record entry, placed at the common upper level covering those sections or at a clearly designated owner location; each affected section should state only its own consequences and include a single link reference. Do not copy a summary into each section (they will drift apart), and do not split the causal chain across several sections.
2. Define numbering before using it
After numbering something, state what it refers to when it first appears; or simply do not use numbering and describe it directly.
The most typical failure issomething rejected leaves behind a name but not what it refers to: The document repeatedly mentions "deleted," "obsolete," "the plan once adopted," with numbering, yet that numbering was never defined—readers never know what it originally was.
Why this can only be upheld at the time of writing: No one can fill in this definition afterward, and AI certainly cannot—it has no way to know what that numbering refers to, and adding any one is guessing at facts. At the time of writing it is a matter of one sentence; after writing it is a permanent gap.
3. The introduction is the basis for deciding "whether to keep reading"
It is not a dumping ground for content summaries. The introduction gives the conclusion and scope, and details sink down into the corresponding sections.
A counterintuitive reminder: When judging that something is "too dense," do not treat tables and lists as prose. A large structured table isgoodcontent organization—scannable and locatable; prose of the same word count is the disease. When tightening the introduction, look only at the prose portions.
4. The same conclusion is defined in only one place
When the same conclusion is scattered across multiple files, one change requires synchronizing multiple places, and omissions are inevitable. Designate one place as the source, and reference it from other places.
But this is not a prohibition. Repetition is sometimes intentional: test cases quoting the original requirement text are for local readability, and runbooks need to be self-contained offline. The requirement of this rule isto know what cost you are paying, not to deduplicate across the board.
Changing it to a reference is also not free—it turns a self-contained statement into a dynamic dependency on another document, and may lose local context. Whether to deduplicate requires judgment; do not apply it mechanically.
5. Write for people who lack your current context
This is the root of "jargon." The writer was omniscient at the time, so they could not see which words needed explanation—a few-hundred-character introduction stuffed with ten undefined identifiers, internal abbreviations, and cross-references to sections, without any awareness while writing.
AI is always the "omniscient at the time" party, so this problem systematically worsens in AI writing. No step makes the writer discover it themselves—reviewers often have just come out of the same context.
What to do: after writing, ask one question—can someone without today's conversation understand this passage?
Boundaries
markdown-stylegoverns "what markup to use" (heading levels, code block languages, spaces between Chinese and English, full-width punctuation), while this skill governs "where information goes." Lists nested too deeply or lists containing only one item are markup usage and belong tomarkdown-stylecode-qualitygoverns code, while this skill governs documents- This skill does not govern writing style—whether sentences are awkward, whether terminology density is high or low, whether it "reads comfortably"—all of these require rewriting sentences to improve, which is beyond the boundary