Reduce Redundancy from Documentation
Overview
Redundancy slows readers down by forcing them to process repeated information. Documentation should express each concept exactly once, use each phrase once, and remove unnecessary transition words that don't guide meaning. This skill helps identify and fix three types of redundancy: lexical (repeated words/phrases), structural (unnecessary transitions), and semantic (repeated concepts across sections).
Agent Workflow
Phase 1 — Scanning (no edits)
- Read the full document
- Use the Redundancy Detection Guide below to identify violations
- Create one task per redundancy found:
"Remove redundancy – section:(Type:<lexical|structural|semantic>): "
- List all tasks for user confirmation before editing
Phase 2 — Execution
- For each task, apply the appropriate fix strategy (see Fixing Strategies table)
- When removing a repeated definition, add a cross-reference (link) instead
- Preserve all meaning—remove only unnecessary words
- Mark each task
completed as you finish
Phase 3 — Verification
After all tasks complete, compile the documentation:
sbt "docs/mdoc --in <file.md> --out website/<file.md>"
Verify:
- No compilation errors
- Cross-references are valid (no broken links)
- Sections flow naturally after cuts
- Concept clarity is preserved
Report what you cut AND what you left, one line each with the section name. Leaving something is a
finding, not an omission — it says a borderline case was considered and the bound held. A report
listing only cuts can't be told apart from a pass that never noticed the borderline cases at all.
Redundancy Detection Guide
| Type |
How to Identify |
Signal |
Example |
| Lexical |
Word appears 2+ times in same/adjacent sentences where only one is needed |
Synonym appears nearby; removing word keeps meaning intact |
"return back", "free gift", "unexpected surprise" |
| Lexical |
Same phrase repeats in consecutive paragraphs |
Copy-paste patterns; look for identical 3+ word phrases |
Same code snippet introduced identically twice |
| Structural |
Transition words that don't clarify sequence or relationship |
Removing "furthermore", "also", "in particular" leaves meaning clear |
"Furthermore, also," (both signal addition); "In this regard," when context is obvious |
| Structural |
Signposting phrase that restates what was just said |
Phrase like "as mentioned above" or "as we discussed" |
"We showed earlier that X works. As mentioned above, X is useful." |
| Semantic |
Type defined or explained in 2+ places |
Same definition appears in different sections; same type signature shown multiple times |
"Chunk is an immutable sequence" appears in Overview, Use Cases, and API section |
| Semantic |
Example pattern repeats across sections |
Same use-case explained with similar code/narrative structure |
Multiple "hello world" examples in consecutive sections |
| Semantic |
Motivation explained more than once |
Concept justified in intro, then justified again later |
"We need deduplication for performance" appears in both Overview and Benefits |
Fixing Strategies
Apply the appropriate strategy based on redundancy type:
| Redundancy |
Strategy |
Example |
| Lexical: synonym nearby |
Remove the redundant word; keep one |
Change "return back" → "return" |
| Lexical: phrase repeats |
Extract to section intro or single location; use cross-reference |
Define once at top; link from repeated locations |
| Structural: unnecessary transition |
Delete transition word; verify sentence still flows |
Delete "Furthermore,"; sentence should still read naturally |
| Structural: restated signposting |
Remove phrase; rely on document flow |
Delete "As mentioned above," — reader can infer from prior section |
| Semantic: repeated definition |
Keep definition in primary location (earliest, or most prominent); replace repeats with [See X](#link) |
First definition in Overview; later sections link to it |
| Semantic: repeated example |
Leave it — do not remove a code block, ever. See "Never edit a code block" below. |
Two similar examples stay two examples |
| Semantic: repeated motivation |
Keep motivation in one place (usually intro); remove from later sections |
Explain "why" once; don't repeat in each section |
Common Mistakes
| Mistake |
Why It Fails |
Fix |
| Over-aggressive cutting |
Removing context leaves section unclear |
Remove only redundancy; preserve concept explanations |
| Removing ANY example code block, even "keeping the best and cutting duplicates" |
mdoc blocks share one scope down the whole page — deleting one can break every block after it, and the compile error will point at a line you never touched, far from the block you actually cut |
Never remove a code block, full stop. Two examples that look alike stay two examples; see "Never edit a code block" below |
| Removing type definition completely |
Later sections may reference it without context |
Always keep definition in first/primary location; link from others |
| Breaking cross-references |
Links become invalid after moving content |
Verify links after removing redundant sections |
| Removing transitions that clarify logic |
Some transitions guide meaning ("first", "then", "because", "instead", "unless") |
Only remove decorative transitions ("furthermore", "also") |
| Cutting without re-reading |
Section becomes grammatically broken |
Always read edited section aloud after cutting |
| Cutting a fact because it looks like repetition |
If the text carries information that appears nowhere else on the page — a parameter, a default, a caveat, a version — it is not redundancy |
A cut removes words, never facts |
| Deleting the last of anything |
The last example, the last definition, the last mention of a member — a section reduced to a heading and a link is worse than a repetitive one |
Keep at least one occurrence of every fact and every example, always |
| Treating two distant mentions as redundancy |
A term recurring in two far-apart sections is a reader finding their place, not repetition — cutting it costs more than it saves |
Require three or more occurrences before a lexical repeat counts (see Detection Hints) |
Never Edit a Code Block
Prose is the only target of this skill. mdoc blocks share one scope down the whole page, so removing a
"duplicate" example can break every block that follows it — and the compiler will blame a line you
never looked at, far from the block you actually deleted. The cost of being wrong is a broken page; the
saving from cutting a look-alike example is a few lines a reader can skip. Never worth the trade:
- ✅ cut the sentence introducing the second of two similar examples ❌ cut the example itself
- ✅ leave two code blocks that look alike ❌ merge them into one
Headings, frontmatter, and links are not this skill's to restructure either — do not merge sections,
renumber headings, or retitle anything in the name of reducing repetition.
Detection Hints
- Grep for repeated phrases:
grep -c "<phrase>" <file.md> — require three or more occurrences
before it counts; two distant mentions is a reader finding their place, not repetition
- Read for transitions: Scan for words: "also", "furthermore", "moreover", "in addition", "as mentioned", "as we discussed", "in this regard"
- Count type mentions: Each type should have at most one full definition; others should cross-reference
- Scan for patterns: Look for identical code structures or narrative patterns in consecutive examples — note them for the receipt, never for deletion
Integration
After completing this skill, the document is ready for:
- Stylistic review: Use
/docs-writing-style to check prose rules
- Compliance check: Use
/docs-check-compliance to audit against all rules
- Integration: Use
/docs-integrate if adding the document to the site
1---2name: docs-reduce-redundancy3description: Remove redundant content from documentation. Use when sections repeat information unnecessarily, type definitions appear multiple times, concepts are introduced more than once, or transition words clutter meaning. Reduces cognitive load through deduplication and strategic cross-referencing.4---56# Reduce Redundancy from Documentation78## Overview910Redundancy slows readers down by forcing them to process repeated information. Documentation should express each concept exactly once, use each phrase once, and remove unnecessary transition words that don't guide meaning. This skill helps identify and fix three types of redundancy: **lexical** (repeated words/phrases), **structural** (unnecessary transitions), and **semantic** (repeated concepts across sections).1112## Agent Workflow1314**Phase 1 — Scanning (no edits)**15161. Read the full document172. Use the Redundancy Detection Guide below to identify violations183. Create one task per redundancy found:19 - `"Remove redundancy – section:`<name>` (Type: `<lexical|structural|semantic>`): `<description>`"`204. List all tasks for user confirmation before editing2122**Phase 2 — Execution**23241. For each task, apply the appropriate fix strategy (see Fixing Strategies table)252. When removing a repeated definition, add a cross-reference (link) instead263. Preserve all meaning—remove only unnecessary words274. Mark each task `completed` as you finish2829**Phase 3 — Verification**3031After all tasks complete, compile the documentation:32```33sbt "docs/mdoc --in <file.md> --out website/<file.md>"34```3536Verify:37- No compilation errors38- Cross-references are valid (no broken links)39- Sections flow naturally after cuts40- Concept clarity is preserved4142Report what you cut AND what you left, one line each with the section name. Leaving something is a43finding, not an omission — it says a borderline case was considered and the bound held. A report44listing only cuts can't be told apart from a pass that never noticed the borderline cases at all.4546## Redundancy Detection Guide4748| Type | How to Identify | Signal | Example |49|------|-----------------|--------|---------|50| **Lexical** | Word appears 2+ times in same/adjacent sentences where only one is needed | Synonym appears nearby; removing word keeps meaning intact | "return back", "free gift", "unexpected surprise" |51| **Lexical** | Same phrase repeats in consecutive paragraphs | Copy-paste patterns; look for identical 3+ word phrases | Same code snippet introduced identically twice |52| **Structural** | Transition words that don't clarify sequence or relationship | Removing "furthermore", "also", "in particular" leaves meaning clear | "Furthermore, also," (both signal addition); "In this regard," when context is obvious |53| **Structural** | Signposting phrase that restates what was just said | Phrase like "as mentioned above" or "as we discussed" | "We showed earlier that X works. As mentioned above, X is useful." |54| **Semantic** | Type defined or explained in 2+ places | Same definition appears in different sections; same type signature shown multiple times | "`Chunk` is an immutable sequence" appears in Overview, Use Cases, and API section |55| **Semantic** | Example pattern repeats across sections | Same use-case explained with similar code/narrative structure | Multiple "hello world" examples in consecutive sections |56| **Semantic** | Motivation explained more than once | Concept justified in intro, then justified again later | "We need deduplication for performance" appears in both Overview and Benefits |5758## Fixing Strategies5960Apply the appropriate strategy based on redundancy type:6162| Redundancy | Strategy | Example |63|-----------|----------|---------|64| **Lexical: synonym nearby** | Remove the redundant word; keep one | Change "return back" → "return" |65| **Lexical: phrase repeats** | Extract to section intro or single location; use cross-reference | Define once at top; link from repeated locations |66| **Structural: unnecessary transition** | Delete transition word; verify sentence still flows | Delete "Furthermore,"; sentence should still read naturally |67| **Structural: restated signposting** | Remove phrase; rely on document flow | Delete "As mentioned above," — reader can infer from prior section |68| **Semantic: repeated definition** | Keep definition in primary location (earliest, or most prominent); replace repeats with `[See X](#link)` | First definition in Overview; later sections link to it |69| **Semantic: repeated example** | **Leave it — do not remove a code block, ever.** See "Never edit a code block" below. | Two similar examples stay two examples |70| **Semantic: repeated motivation** | Keep motivation in one place (usually intro); remove from later sections | Explain "why" once; don't repeat in each section |7172## Common Mistakes7374| Mistake | Why It Fails | Fix |75|---------|-------------|-----|76| Over-aggressive cutting | Removing context leaves section unclear | Remove only redundancy; preserve concept explanations |77| **Removing ANY example code block**, even "keeping the best and cutting duplicates" | mdoc blocks share one scope down the whole page — deleting one can break every block after it, and the compile error will point at a line you never touched, far from the block you actually cut | **Never remove a code block, full stop.** Two examples that look alike stay two examples; see "Never edit a code block" below |78| Removing type definition completely | Later sections may reference it without context | Always keep definition in first/primary location; link from others |79| Breaking cross-references | Links become invalid after moving content | Verify links after removing redundant sections |80| Removing transitions that clarify logic | Some transitions guide meaning ("first", "then", "because", "instead", "unless") | Only remove decorative transitions ("furthermore", "also") |81| Cutting without re-reading | Section becomes grammatically broken | Always read edited section aloud after cutting |82| Cutting a fact because it *looks* like repetition | If the text carries information that appears nowhere else on the page — a parameter, a default, a caveat, a version — it is not redundancy | A cut removes words, never facts |83| Deleting the last of anything | The last example, the last definition, the last mention of a member — a section reduced to a heading and a link is worse than a repetitive one | Keep at least one occurrence of every fact and every example, always |84| Treating two distant mentions as redundancy | A term recurring in two far-apart sections is a reader finding their place, not repetition — cutting it costs more than it saves | Require three or more occurrences before a lexical repeat counts (see Detection Hints) |8586## Never Edit a Code Block8788Prose is the only target of this skill. mdoc blocks share one scope down the whole page, so removing a89"duplicate" example can break every block that follows it — and the compiler will blame a line you90never looked at, far from the block you actually deleted. The cost of being wrong is a broken page; the91saving from cutting a look-alike example is a few lines a reader can skip. Never worth the trade:9293- ✅ cut the sentence introducing the second of two similar examples ❌ cut the example itself94- ✅ leave two code blocks that look alike ❌ merge them into one9596Headings, frontmatter, and links are not this skill's to restructure either — do not merge sections,97renumber headings, or retitle anything in the name of reducing repetition.9899## Detection Hints100101- **Grep for repeated phrases**: `grep -c "<phrase>" <file.md>` — require three or more occurrences102 before it counts; two distant mentions is a reader finding their place, not repetition103- **Read for transitions**: Scan for words: "also", "furthermore", "moreover", "in addition", "as mentioned", "as we discussed", "in this regard"104- **Count type mentions**: Each type should have at most one full definition; others should cross-reference105- **Scan for patterns**: Look for identical code structures or narrative patterns in consecutive examples — note them for the receipt, never for deletion106107## Integration108109After completing this skill, the document is ready for:110- **Stylistic review**: Use `/docs-writing-style` to check prose rules111- **Compliance check**: Use `/docs-check-compliance` to audit against all rules112- **Integration**: Use `/docs-integrate` if adding the document to the site
zio