Update the /audit-docs for shorter passages

.claude/rules/docs-authoring.md

@@ -13,6 +13,7 @@ When creating or editing any markdown file, follow the discipline below. These a
 - **Zero hallucination.** Document only what the code provably does. Read the implementation; don't infer behaviour from a name, type, comment, file location, or familiar pattern.
 - **Prove it.** Before writing any technical claim, know the exact file (and ideally lines) that prove it. If you can't, don't write it. Silence beats speculation: no "appears to", "should", "will", or planned/intended behaviour.
 - Fix existing statements that contradict the code.
+- **Compress, don't just delete, an overlong comment.** Removing bloat means deleting a comment that restates the code; where a comment explains a genuinely non-obvious internal but runs far longer than that content needs, compress it to the non-obvious fact instead of leaving it, since being accurate is not, on its own, a reason a comment stays at whatever length it was written.
 - **Current state only.** Describe the code as it is now, in prose and in comments alike. Never narrate the past ("replaces", "used to", "formerly", "for the first time", "unlike the old") and never name a file, flag, or tool that no longer exists: git carries that history, and a reader cannot check a claim against something that is gone. Future intent lives in a `TODO` in the code, never in the documentation. **Name the line a comment describes**, and delete the comment where no line corresponds: that is the test the phrase list misses, and a comment explaining why something was removed is what it catches, since its subject is a decision and its reader is looking at the pull request. Rationale worth keeping goes in a decision record of its own under [`docs/`](../../docs/index.md), created when the first one is needed, rather than scattered through the files it explains.
 
 ## Style
@@ -25,7 +26,9 @@ When creating or editing any markdown file, follow the discipline below. These a
 - Document a tunable value by the **name a consumer changes it by** (env var, config key, CLI flag, or a named member of a centralized constants/config module that other code reads), judging by role, not location. Don't document an ephemeral local variable as the config surface.
 - **Acronyms** in prose you write or edit use capitals (ID, URL) and are expanded on first use per doc ("Deoxyribonucleic acid (DNA)"). Keep exact casing for brand/tool/package names (npm, iOS), domain terms (snRNA), and direct code references (an `id` field).
 - No placeholders, TODOs, or empty "add details here" sections.
-- **Two readers, one document.** Every page is read by a newcomer meeting the system for the first time and by someone who already works in it, and serving only the second is the ordinary failure. Serve both by order rather than by splitting the page: what the subject is and why a reader would reach for it, what that reader must already have or have read, then the depth in full. A page only its author can follow is not finished, and neither is one whose reader could have got it faster from the source.
+- **Two readers, one document.** Every page is read by a newcomer meeting the system for the first time and by someone who already works in it, and serving only the second is the ordinary failure. Serve both on one page, by order rather than by splitting it between them: what the subject is and why a reader would reach for it, what that reader must already have or have read, then the depth in full. A page only its author can follow is not finished, and neither is one whose reader could have got it faster from the source. A page that grows too long as a whole still splits by length, not by reader; see the next bullet.
+- **Brevity is measured too, not only whether each paragraph earns its place.** Judge the whole document: would a careful human asked to write the same brief have produced something shorter? Where a page mixes a brief overview with deep reference, how-to, or explanation content, split it into a short overview (a README or index) and a dedicated depth page, filed by the same directory-type-precedent logic a new file already uses. This is a judgement call, not a word or line count, worked through in [`writing-for-both-readers.md`](../skills/audit-docs/references/writing-for-both-readers.md#document-length-as-a-whole).
+- **Complement a passage that stays long, rather than only cutting it.** Where a passage survives the trim above because the subject needs it, consider whether a Mermaid diagram (never defaulting to `flowchart`, chosen per [`diagram-and-image-accessibility.md`](../skills/audit-docs/references/diagram-and-image-accessibility.md#choosing-the-mermaid-diagram-type)), a table, a code/config snippet, or an image would let a reader absorb it faster than prose alone. Weigh this more heavily as the passage grows longer, though a short passage can use it too where one of these forms fits the content better than prose.
 - **Introduce every term of art where the document first uses it**, in a short parenthesis or by a link to the document that defines it, then use it unchanged. Expanding an acronym is not introducing it, since the expansion is often as opaque as the abbreviation. Spell a concept one way across [`docs/`](../../docs/index.md): a concept spelled three ways is three concepts to anyone meeting it, and it defeats their search.
 - A document opens with a single H1 named for its file, then a one to three sentence introduction for a reader who does not yet know the subject, then H2s. Headings are unique and fully descriptive ("Retry backoff limits", not "Limits"), because anchors are generated from them, and use sentence case.
 - **Tables only for uniform data scanned quickly.** If columns repeat across rows, cells sit empty, or a cell holds a sentence of prose, use a list instead.

.claude/skills/audit-docs/SKILL.md

@@ -77,6 +77,7 @@ Each procedure reports findings rather than edits, so every decision stays with
 - **Record each document's type in that inventory,** under the **Diátaxis** framework, decided by what its reader needs rather than by its subject: content informing action serves the acquisition of skill as a tutorial and its application as a how-to guide, and content informing cognition serves acquisition as an explanation and application as a reference. A set can be complete and accurate and still have no way in. Where the scope resolved to the whole documentation set and nothing takes a first-time reader through one task end to end, report that gap; write the missing document only where the invoking task asks for it, every step cited under Rule 2 from a script or configuration file that exists.
 - Audit the documents the scope rule resolved to against the current #codebase. That is all of `docs/` only where the rule resolved to the whole documentation set, and on a pull request it is the documents describing the changed code. **Correct** pre-existing content that contradicts the code, preserving accurate content's phrasing and style. **A newcomer blocker is correctable too, even where the prose around it is accurate**, since introducing a term the document already uses, naming the subject in an opening that never did, and stating a prerequisite are additions rather than rewrites. Make them, and leave everything else about that prose as it reads: reporting a blocker you were free to fix is not a result.
 - **Delete** pre-existing content only if it is massively duplicated, describes removed features, or fundamentally cannot be corrected. Default to correcting, not deleting. Your own generated content may be edited or removed freely when wrong.
+- **Split** a document whose scope mixes a brief overview with deep reference, how-to, or explanation content (Rule 6), rather than leaving the two layered on one page. File the resulting overview and depth pages the same way Create does below: by matching each to a directory whose existing siblings are the same Diátaxis type.
 - **Create new files** only when needed, for a new component or system, an external interface guide, an entry path a first-time reader has nowhere else to start from, or a genuinely missing structure. **Decide the directory before writing a word, and decide it by document type rather than by subject.** Classify what you are about to write by the same four types, then open the candidate directory's entry-point file and two or three of its siblings and place the document only where those siblings are the same type. A directory's name is a claim about what it holds, so a how-to guide filed among explanations is in the wrong place even where its subject belongs to that area, and a reader who trusted the directory now has to read it to find out. **Precedent settles it where precedent exists:** a sibling of the same type already in that directory makes the placement correct, and the new document joins it. The directory merely touching the same topic is not precedent. Where no directory holds that type, create one with an entry-point file named as the project's existing directories name theirs. State in your output which directory you chose and which sibling or precedent decided it.
 - **Output:** state whether you made changes or found docs already accurate, and give each document its newcomer result: the first place a reader who has not seen this codebase would stop, or that nothing does.
 
@@ -85,7 +86,7 @@ Each procedure reports findings rather than edits, so every decision stays with
 **Mandatory.** Execute regardless of Phase 1 and 2 results. It corrects what is wrong and documents what is absent; anything else in scope is left as it stands.
 
 - **Scope:** the code the scope rule above resolved to, covering its documentation comments, inline comments, and file-level headers, plus every `.md` file inside that scope which sits outside `docs/`. A file the rule did not resolve to stays out whatever it contains, so this phase is never a repository-wide sweep for markdown, for undocumented symbols, or for a comment pattern.
-- **Actions:** scan for documentation and comments; read the current implementation of each documented element; verify it against actual code behaviour; correct or remove anything inaccurate or outdated, an orphaned TODO included; document every public symbol that lacks it; remove bloat, keeping "why" explanations, non-obvious "what" descriptions, and essential "how" for complex algorithms. Removing bloat means deleting comments that restate the code, never comments that explain a non-obvious internal.
+- **Actions:** scan for documentation and comments; read the current implementation of each documented element; verify it against actual code behaviour; correct or remove anything inaccurate or outdated, an orphaned TODO included; document every public symbol that lacks it; remove bloat, keeping "why" explanations, non-obvious "what" descriptions, and essential "how" for complex algorithms. Removing bloat means deleting a comment that restates the code. Where a comment explains a genuinely non-obvious internal but runs far longer than that content needs, do not delete it; compress it to the non-obvious fact and cut the padding, restated setup, or narrated reasoning around it. An accurate comment being lengthy is not, on its own, a reason to leave it exactly as found.
 - **Always document the public surface.** Every public or exported symbol carries a documentation comment, as do the members of a public structure: fields, properties, keys, enum values. Write for a reader meeting the symbol for the first time, assuming they can infer nothing from its name. Reach for what the declaration cannot express, such as why it exists, a constraint, an invariant, or a caller obligation. Where no such explanation exists, a plain restatement of what the symbol does is correct: being obvious is not a defect on a public surface, being absent is. **Rule 2 still governs, and it comes first.** Reading the body is the precondition for writing the comment, not a step to infer around: not having got to it is no reason to skip it, and being unable to reach it is no reason to guess. Where you have not read the body, leave the symbol as it is and name it in your output: undocumented and reported is a compliant result, where a comment written from the symbol's name is the defect this rule exists to prevent.
 - **Do not restate what the language's own syntax declares**, such as a type, a visibility modifier, or an override marker. This governs what you write in a **new** documentation comment and never licenses removing an existing one.
 - **Correct an existing documentation tag; do not strip or delete it.** A parameter, return, throws, or example entry was written deliberately. Read enough surrounding code to judge it, then fix what is factually wrong and leave what is right, including parts a convention would omit in new code. Removing a tag, or a piece of one, because it looks redundant is restyling someone else's work, not auditing it. Delete a whole tag only when it is wrong and uncorrectable, such as one documenting a parameter the signature no longer has. Phase 2's "default to correcting, not deleting" governs in-code documentation too.
@@ -145,6 +146,14 @@ No exceptions. Do not output any diagram missing either field.
 
 Images are held to the same bar: every image carries alt text conveying what it shows. Generic alt text ("screenshot", "diagram") fails exactly as an absent `accDescr` does. Use an image only where showing is easier than describing.
 
+### Rule 6: Brevity and document scope
+
+A document's total length is measured too, not only whether each paragraph in it earns its place. Before finishing a document, judge the whole page: would a careful human asked to produce the same brief have written something shorter? If so, cut restated context, a point made more than once across sections, and depth that belongs on another page, rather than defending every sentence in isolation. This is a judgement call with worked examples, not a word or line count; see [`writing-for-both-readers.md`](references/writing-for-both-readers.md#document-length-as-a-whole) before trimming an existing document.
+
+**Split an overview from its depth.** Where a document's scope mixes a brief orientation (what the subject is, why a reader reaches for it) with deep reference, how-to, or explanation content, split it: a short overview (a README or an index) that orients and links out, and a dedicated page under the matching Diátaxis directory carrying the depth, filed by the same directory-type-precedent logic Phase 2 uses for any new file. Apply this only where a page is found mixing both; it is not a blanket requirement that every document split into two.
+
+**Complement text that remains long, rather than only cutting it.** A picture is worth a thousand words: where a passage survives the trim above because the subject genuinely requires that much explanation, consider whether a Mermaid diagram, a table, an interface/config snippet, or an image would let a reader absorb it faster than prose alone, and add whichever fits rather than leaving prose as the only carrier. Judge the diagram type by what the content actually is, never defaulting to `flowchart` (§5, and see [`diagram-and-image-accessibility.md`](references/diagram-and-image-accessibility.md#choosing-the-mermaid-diagram-type)); use a table only for uniform data scanned quickly; use a snippet only within the code-snippet allowance in section 3. Weigh this more heavily as the passage grows longer, though it applies to a short passage too where one of these forms would be clearer than prose. It supplements the significance filters in §4 and §5 rather than overriding them: a complement still needs a diagram-worthy subject or table-worthy data, grounded in code read this run like any other claim.
+
 ---
 
 ## 3. Writing Guidelines
@@ -243,4 +252,7 @@ Then confirm:
 - Rendered output was checked, not only the source: diagrams parse, nested lists render, and documentation comments display the intended text. Every table you touched was re-read whole, with each row's cell count matching its header and no cell broken across lines.
 - Every document you created sits in a directory whose existing documents are the same Diátaxis type, or in a new directory created for that type, and your output names the directory and what decided it.
 - No comment you wrote or kept describes something the file does not contain, and every comment you deleted on that ground was one you could not attach to a line.
+- No comment, existing or new, runs longer than what it documents: an accurate but disproportionately long comment was compressed to its non-obvious content (Phase 3), not left in place because it was not wrong.
+- Every document read in full this run, judged as a whole rather than paragraph by paragraph, is no longer than a careful human would have written for the same brief (Rule 6); a page found mixing a brief overview with deep reference, how-to, or explanation content was split rather than left layered.
+- A passage that stayed long after Rule 6's trim was weighed for a complementary diagram, table, code/config snippet, or image (Rule 6), and one was added where it fit the content.
 - Phase 3 ran and its result is reported.