# Doc Review

> Reviews a document against a predetermined checklist: clarity, undefined terms, unenforced rules, undated decisions, missing owners, contradictions, and obvious stale content. Use when the user says "review this doc", "review this page", "check this before I publish", or pastes a document and asks for a check before sharing it. Read-only -- it reports findings, it never edits or rewrites the document.

- Skill: `by-carlos/doc-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add by-carlos/doc-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/by-carlos/doc-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: by-carlos (https://skillmd.com/u/by-carlos)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/by-carlos/doc-review

---


# Doc review

A fixed-checklist review of one document. It finds problems and says where
they are and why they matter. It does not fix them.

## Hard rule: never rewrite

This skill reports. It does not edit the document, propose replacement text
for more than a short illustrative phrase, or produce a "fixed" version. The
human edits. Say this up front if there is any risk of the request being read
as "clean this up for me".

## Step 1: get the document

- **A link was given.** Fetch it with whatever tool is connected for that
  source -- Confluence, Google Docs, a web page, a local file path. Use the
  live content, not the link text.
- **Text was pasted.** Use it as-is. Do not go looking for more.
- **Nothing was given.** Ask for a link or a paste. Do not search for it or
  guess which document is meant.

If a fetch fails, say what failed and ask for a paste. Do not review a title
or a summary in place of the real content.

## Step 2: run the checklist

Evaluate the document against each of these. A document can trip any number of
them, including zero.

- **Clarity.** A sentence or section whose meaning takes more than one reading
  to get, or that could mean two different things.
- **Readability for non-native English speakers.** Long sentences, uncommon
  words with a common alternative, idioms, or culturally-specific references.
- **Undefined terms and unexpanded acronyms.** A term or acronym used before
  it is defined, or never defined at all, where a reader new to the subject
  would stumble.
- **Rules with no enforcement or owner.** A "must" or "should" statement with
  nobody named to enforce it and no mechanism that would catch a violation.
- **Decisions with no date.** A decision stated as settled, with no date
  attached, so a reader cannot tell how current it is.
- **Missing owners.** A task, section, or piece of ongoing work with nobody
  named responsible for it.
- **Internal contradictions.** Two parts of the same document that cannot both
  be true, or that give conflicting instructions.
- **Content stale on its face.** A reference to a date, version, tool, or
  event that has clearly passed or changed, judged from the document's own
  content -- not from outside knowledge of what changed.

Do not invent a finding to fill out the list. A clean document produces a
short report, not a padded one.

## Step 3: cap and order

Findings are capped at a flat 5, hardest first, using the same hardest-first
ordering and parked-by-title treatment as `self-review` -- consistency in how
the two review skills order and park findings is worth more than either skill
inventing its own scheme. This skill's cap does not tone-scale the way
`self-review`'s does. "Hardest" here means most likely to cause real harm if
unfixed: a contradiction or an unenforced rule outranks a wording nit. Within
a tier, order by where the finding sits in the document (earliest first),
since that is the order a reader will hit them.

If there are more than 5, name the count and list the rest by one-line title
only, the same parked-by-title treatment `self-review` uses.

## Step 4: report

The report follows `${CLAUDE_PLUGIN_ROOT}/docs/response-format.md` -- read it
before writing the reply; `profile.tone` scales any narration around the
findings, never the findings themselves. Lead with a one-line summary: how
many findings, and whether anything is parked. Then one entry per finding, in
the order fixed by Step 3:

```
1. [checklist category] -- <one-line title>
   Where: <section heading, or a short quote that locates it>
   Why it matters: <what goes wrong if this ships as-is>
   Fix: <a concrete, specific fix -- not "make this clearer">
```

If nothing qualifies, say so plainly rather than omitting the report:

```
No findings. <document name> reads clearly, has no undefined terms, and
nothing on this checklist tripped.
```

## Failure cases

| Situation | What to do |
|---|---|
| Link given but no tool is connected for that source | Say which source and that no tool is connected; ask for a paste instead. |
| Fetched content is empty or clearly truncated | Say so and ask for a paste rather than reviewing a partial document. |
| Document is very long | Review the whole thing. Do not sample or skip sections silently. |
| User asks for the document to be rewritten or fixed | Decline per the hard rule above; offer the findings instead. |