--- name: docs-review-aae05be42fda description: | Score a technical doc (RFC, ADR, README, CLAUDE.md, blog-style post) against the 5-category 100-point rubric in .rules/docs-rubric.md. Read-only audit. Surfaces top issues by severity. Defers to existing user-level skills (blog-llm-tells, blog-factcheck, blog-overlap, blog-argument-shape, blog-pre-publish) for prose-quality dimensions rather than re-deriving them. Use when the user says "review docs", "audit docs", "score this doc", "doc quality", "docs review". allowed-tools: Read, Grep, Glob, Bash --- # Docs Review Skill ## When to apply Use when scoring an existing technical doc — RFC, ADR, README, CLAUDE.md, architecture doc, blog-style technical post. Read-only; produces a punch list, not a rewrite. The active counterpart is `docs-rewrite` which runs review → research → rewrite → validate. Trigger keywords: review docs · audit docs · score this doc · doc quality · docs review · doc audit. ## Inputs - A single file path, OR - A URL the operator wants reviewed (fetched + reviewed in-place), OR - A directory (batch mode — score every doc, sort by score) ## Workflow ### Step 1 — Read the doc + extract structural facts Mechanical extraction (no judgment yet): - Heading structure (H1 / H2 / H3 with hierarchy) - Paragraph count + word counts per paragraph - Sentence-length distribution (for burstiness analysis below) - Citations present (any inline `(source, year)` form) - Info-gain markers (`[ORIGINAL DATA]` / `[PERSONAL EXPERIENCE]` / `[UNIQUE INSIGHT]`) - Code blocks with language tag - Internal `./other-doc.md` and `#anchor` references - Frontmatter (title / description / tier / keywords) Cite the file paths + line numbers wherever you observe a problem. ### Step 2 — Run the deferred-to user-level skills The rubric **defers** the prose-quality lenses to existing user-level skills. Run them and quote their findings into the score, **don't re-derive them inline**: | Rubric category | Defer to | Quote | | ------------------------------------------- | -------------------------------- | --------------------------------------------- | | Argument Strength § thesis + falsifiability | `blog-argument-shape` | "Thesis: . Falsifiability: ." | | Source / Evidence § citations verified | `blog-factcheck` | The skill's punch list, as-is. | | Content Quality § AI-tell scan | `blog-llm-tells` | The skill's findings, as-is. | | Structure § cross-doc consistency | `blog-overlap` (when applicable) | STRONG / MODERATE / WEAK | If `blog-pre-publish` is available, run it as a single invocation — that's the orchestrator that bundles the four. Quote its consolidated punch list. ### Step 3 — Score the technical-doc-specific dimensions These have no analog in the user-level skills; this is where `docs-review` adds value: **Argument Strength (20 pts) — partial:** "Locatable thesis" `[M]` + "Close revisits the thesis" `[J]` + "One claim per doc" `[J]` are scored here even though the deeper lenses defer. (4 + 3 + 2 = 9 pts of the 20 from the skill alone; the remaining 11 come from `blog-argument-shape`.) **Source / Evidence (25 pts) — partial:** "Inline citations on every claim" `[M]`, "Year + URL + retrieval date" `[M]`, "Code/spec links resolve" `[M]`, "First-hand evidence flagged" `[M]` are mechanical checks (12 pts). The remaining 13 come from `blog-factcheck` + tier verification (manual judgment). **Content Quality (25 pts) — partial:** "Answer-first H2s" `[M]`, "Sentence discipline" `[M]`, "Paragraph discipline" `[M]`, "H2 cadence" `[M]`, "Glossary / first-use definitions" `[M]` (18 pts) are mechanical. AI-tell scan defers to `blog-llm-tells` (4 pts). "No unsupported assertion" is judgment (3 pts). **Structure (20 pts) — fully scored here:** heading hierarchy, code blocks valid, internal links resolve, summary box / TL;DR, frontmatter on tier-1/2 docs (per CLAUDE.md `FRONTMATTER_REQUIRED_FILES` gate), spec/RFC alignment, file-size + sprawl. Cross-doc consistency defers to `blog-overlap`. **Diátaxis audit (no extra points):** run `skills/diataxis` in audit mode. Report each mixed-mode passage, and any mismatch between the declared `diataxis:` type and the inferred one, as a Structure finding with its quoted evidence. Missing or invalid `diataxis:` / `audience:` frontmatter is a Structure finding too. **Audience Fit (10 pts) — fully scored here:** persona-appropriate readability band (advisory), reader's prior knowledge stated, length matches purpose, examples for the audience. ### Step 4 — Surface top 10 issues Don't dump every observation. Bin into Critical / High / Medium / Low and surface only the top 10. Reviewers won't act on a 47-item punch list. For each issue, output: - **Severity:** Critical / High / Medium / Low - **File:line** (or section) - **Category:** Argument / Source / Content / Structure / Audience - **Observation:** what's wrong (mechanical: cite the rule; judgment: state the criterion) - **Recommendation:** what to do ### Step 5 — Output the score ```text # Docs Review: **Score: 78 / 100** (prior baseline: 71 / 100; +7) | Category | Score | Top issues | | ----------------- | ------- | ---------- | | Argument Strength | 16 / 20 | thesis is hedged (first paragraph has 3 questions) | | Source / Evidence | 19 / 25 | 2 unverified citations (per blog-factcheck) | | Content Quality | 21 / 25 | passive voice 14% (target ≤ 10%) | | Structure | 15 / 20 | code-block in §3.2 missing language tag | | Audience Fit | 7 / 10 | Flesch 22 (band 30-50 for technical docs) — too dense | ## Top 10 issues 1. [Critical] file.md:42 — Argument: thesis is buried under 3 hedging questions. Recommend: hoist a single declarative claim to the first paragraph. 2. [High] file.md:128 — Source: "studies show 80% improvement" has no citation. Recommend: add (source, year) or remove the claim. ... (8 more) ``` ## What this skill does NOT do - **Edit the file.** Read-only by design. For active rewrite, use `docs-rewrite`. - **Re-implement AI-tell detection / fact-checking / argument-shape analysis.** Those defer to user-level skills. - **SEO scoring / schema validation.** Out of scope for code-governance docs; rubric explicitly excludes. - **Score every dimension equally.** Argument Strength weights 20%; Source/Evidence 25%; Structure (the technical-doc-specific category) 20%. Don't dilute by treating all dimensions identically. ## See also - `.rules/docs-rubric.md` — the canonical rubric this skill applies - `skills/docs-rewrite` — the active rewrite counterpart (uses the same rubric for audit + validate) - `skills/documentation-management` — operating manual for doc work - `skills/diataxis` — document-type audit and the frontmatter contract - User-level `blog-pre-publish` — orchestrator for the prose-quality lenses --- Source attribution: nexus-substrate Original project: https://github.com/nexus-substrate/nexus-agents/blob/ddc209542969af8515e8424e45f93905e445d81c/skills/docs-review/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 William Zujkowski Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## Additional upstream notices docs-review-aae05be42fda/DAVEAI-UPSTREAM-NOTICE nexus-agents Copyright (c) 2026 William Zujkowski This project is inspired by and incorporates concepts from claude-team-mcp, which is also licensed under the MIT License. Attribution is preserved per the terms of the original license. # Mega AI Hub resource metadata Creator / publisher: nexus-substrate Original project: https://github.com/nexus-substrate/nexus-agents/blob/ddc209542969af8515e8424e45f93905e445d81c/skills/docs-review/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Education & Research, Product Management Roles: Product Manager, Researcher, Technical Writer Specialties: API Tools: Grep Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 3a7de06bf66b39fb67e3e068be8cc3006d88acc7009fbc38cccbe96e2d647a52