// 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.
| name | docs-reduce-redundancy |
| description | 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. |
| argument-hint | [path/to/doc.md] |
| allowed-tools | Read, Edit, Bash, Grep |
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).
Phase 1 — Scanning (no edits)
"Remove redundancy – section:(Type:<lexical|structural|semantic>): "Phase 2 — Execution
completed as you finishPhase 3 — Verification
After all tasks complete, compile the documentation:
sbt "docs/mdoc --in <file.md>"
Verify:
| 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 |
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 | Choose the best/clearest example; remove others; add comparative note if examples show different patterns | Keep one realistic example; remove toy examples |
| Semantic: repeated motivation | Keep motivation in one place (usually intro); remove from later sections | Explain "why" once; don't repeat in each section |
| Mistake | Why It Fails | Fix |
|---|---|---|
| Over-aggressive cutting | Removing context leaves section unclear | Remove only redundancy; preserve concept explanations |
| Cutting example entirely | Readers need at least one concrete example | Keep best example; remove duplicates, not all examples |
| 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") | Only remove decorative transitions ("furthermore", "also") |
| Cutting without re-reading | Section becomes grammatically broken | Always read edited section aloud after cutting |
grep -n "<phrase>" <file.md> to find all occurrencesAfter completing this skill, the document is ready for:
/docs-writing-style to check prose rules/docs-check-compliance to audit against all rules/docs-integrate if adding the document to the siteStop and consult this skill whenever your response would involve any fact or code related to ZIO HTTP. Covers: installation and setup, routing (Routes, RoutePattern, PathCodec), handlers and HandlerAspect, the declarative Endpoint API and HttpCodec, client and server configuration, middleware, request/response/headers/cookies, WebSockets, Server-Sent Events, Body and binary codecs, form data, template DSL, OpenAPI documentation and code generation, authentication (basic, digest, bearer, JWT, OAuth, WebAuthn), TLS/SSL/mTLS, testing, ZIO Config integration, Datastar/HTMX integration, migration, and any ZIO HTTP library versions or dependencies. Trigger this even for coding tasks that import zio.http, content that mentions ZIO HTTP features or types, or comparisons involving ZIO HTTP. Any time you would otherwise rely on memory for ZIO HTTP details, verify here instead — your training data may be outdated or wrong.
Stop and consult this skill whenever your response would involve any fact or code related to ZIO core or the ZIO ecosystem. Covers: ZIO effects and type aliases (ZIO, Task, UIO, UEffect), fibers and fiber management, concurrency primitives (Hub, Queue, Ref, Semaphore), Software Transactional Memory (STM), ZIO Streams (ZStream, ZSink, ZPipeline, ZChannel), ZIO Test framework and test utilities, ZLayer and dependency injection patterns, error management and error types, scheduling and retries, resource management and scoping, ZIO Config, ZIO Schema, ZIO JSON, ZIO Kafka, and all official ZIO libraries and integrations. Trigger this for any ZIO coding task, type signatures, library features, architectural patterns, or comparisons involving ZIO. Any time you would otherwise rely on memory for ZIO details, verify here instead — your training data may be outdated or wrong.
Scans merged GitHub PRs (from latest commit back to an upstream base ref) and produces a documentation-coverage audit report. Processes 20 PRs per batch and asks before continuing to the next batch. Skips PRs already checked in previous runs using a persistent state file. For each new PR, determines whether documentation is required based on labels, changed files, and content signals, then checks whether docs exist and grades coverage using four rubric levels: Well Documented, Partially Documented, Stub, or Not Documented. Outputs a focused report showing only PRs that require docs, sorted by coverage gap severity. Use this skill whenever the user wants to know which merged PRs are missing documentation, wants a documentation debt audit, or asks "what needs to be documented?", "which PRs have no docs?", or similar coverage questions. Invoke it even if the user just says "doc audit" or "show me undocumented changes."
Critique and fix existing documentation files using an automatic review loop. Spawns critics to review docs and makers to fix issues. Iterates until approved or max 3 rounds. Handles single files or directories. Works with available tools.
Shared reference for mdoc code block modifiers and Docusaurus admonitions used across ZIO library documentation skills. Include when writing any documentation that contains Scala code blocks.
Prose style rules for documentation (reference pages, how-to guides, tutorials). Use this skill whenever writing or editing documentation to ensure consistency, clarity, and professionalism across all docs.