zeikar/hyperclaude / skills/hyper-docs-review
hyper-docs-review
UnverifiedUse after documentation edits — typically after the documenter agent runs, or when the user invokes /hyperclaude:hyper-docs-review. Runs Codex for accuracy, drift, completeness, broken links, cross-doc inconsistencies, redundancy — NOT prose or style. Distinct from /hyperclaude:hyper-code-review (code diffs) and /hyperclaude:hyper-plan-review (plans).
hyper-docs-review
Documentation accuracy gate. Sends docs (one or more files, or a directory) to Codex for critique focused on: drift between docs and code, missing coverage, broken or suspect links, contradictions between docs, in-doc duplicated or appended-beside claims (redundancy).
When to use
- User typed
/hyperclaude:hyper-docs-review. - After
hyper-docs-synchas edited docs and you want a Codex accuracy gate.
When to skip
- Docs haven't changed.
- You want a style/prose review (this gate is accuracy-only).
How to invoke
Invocation argument: $ARGUMENTS
--resume is supported. Paths with spaces are unsupported.
Argv grammar
Apply this regex to the trimmed $ARGUMENTS:
^((?:(?!--)\S+\s*)*)(?:--diff-base\s+(\S+))?(?:\s*(--resume)(?:\s+(\S+))?)?\s*$
- Group 1 = zero or more space-separated leading path tokens (split on whitespace in Step 1); each is either an existing file (any type — not just
.md) or, if it's the sole token, an existing directory; empty defaults todocs/. Negative lookahead per-token prevents matching--diff-baseor--resumeas a path. Many files OR one directory — never both. - Group 2 = optional
--diff-base <ref>value - Group 3 = literal
"--resume"token (truthy when present, undefined when not) - Group 4 = optional resume artifact path
When Group 3 is '--resume' (truthy) and Group 4 is undefined, treat as --resume auto.
Valid invocations:
/hyperclaude:hyper-docs-review— reviewsdocs/, fresh run/hyperclaude:hyper-docs-review docs/api.md— reviews single file, fresh run/hyperclaude:hyper-docs-review README.md docs/workflow.md docs/architecture.md— reviews three files, fresh run/hyperclaude:hyper-docs-review README.md site/index.html— mixed file types (.md+.html), fresh run/hyperclaude:hyper-docs-review --resume— reviewsdocs/, resumes from latest artifact/hyperclaude:hyper-docs-review --resume <prev-artifact-path>— resumes from explicit artifact/hyperclaude:hyper-docs-review docs/api.md --diff-base main— single file with diff context/hyperclaude:hyper-docs-review docs/api.md --resume— single file, resume fromauto/hyperclaude:hyper-docs-review docs/api.md --diff-base main --resume <prev-artifact-path>— all options
If the argument doesn't match the regex, ask the user to clarify and stop.
Resume semantics
See ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md for the shared --resume semantics (explicit vs auto fallback, the template-version precondition). Docs-review's identity check keys on the docs-target SET (order-insensitive — not a single scalar).
- Budget exceeded (docs > 200KB after revision): bridge returns
ok:false— NOT fallback. Tell user to narrow scope (fewer--docs-pathfiles, or a smaller subdirectory).
Step 1 — Resolve target
Split Group 1 on whitespace into tokens (or default to docs/ when empty). Classify each token via Bash — [ -f "<path>" ] (existing file → --docs-path) vs [ -d "<path>" ] (existing directory → --docs-dir); a token that is neither → STOP.
| Group 1 tokens | Bridge argv |
|---|---|
| Empty | ['docs-review', '--docs-dir', 'docs/'] |
One or more existing files (each [ -f ], any type) | ['docs-review', '--docs-path', '<path1>', '--docs-path', '<path2>', ...] (one flag per file, in order) |
| Single existing directory path | ['docs-review', '--docs-dir', '<path>'] |
| Anything else (mix of files and a dir, more than one directory, or a path that doesn't exist) | Tell user the contract, ask to clarify, STOP. |
Step 2 — Run the bridge
Use the Bash tool with run_in_background: true (invocation mode: ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md). Pass each argument as a separate token (no shell interpolation of user-supplied substrings):
# Single file
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" docs-review --docs-path docs/api.md
# Directory
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" docs-review --docs-dir docs/
# With diff context
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" docs-review --docs-path docs/api.md --diff-base main
If --diff-base <ref> was matched (Group 2), append --diff-base <ref> to the argv. If --resume was matched (Group 3 truthy), append --resume <value> to the argv, where <value> is Group 4 if present, otherwise auto.
Step 3 — Surface the review
Once the bridge task completes, parse the JSON from its stdout. On ok:true, read the output file with the Read tool. On ok:false, surface the error verbatim:
docs payload exceeds 200KB→ tell user to narrow scope (fewer--docs-pathfiles, or a smaller subdirectory)no .md files in <path>→ tell user the directory has no top-level markdowngit diff exceeds 500KB→ tell user to use a closer--diff-baseref or omit it
Output contract
Docs-review files have YAML frontmatter:
mode: docs-reviewtemplate-version(sourced from the docs-review template's frontmatter)slug(derived from file basename or dir name; multi-file runs use<first>-plus-<n-1>)generated(ISO timestamp)plugin-versioncodex-versiondocs-target(a JSON STRING of the dir path in--docs-dirmode, or a JSON ARRAY of file paths in--docs-pathlist mode)- Optional
diff-base(when--diff-basewas used) codex-input-tokens,codex-cached-input-tokens,codex-output-tokens,codex-reasoning-output-tokens— each emitted independently when Codex reported that token field in usage; omitted when Codex did not emit usage
Followed by sections: ### Findings, ### Gaps, ### Broken Or Suspect Links, ### Cross-Doc Inconsistencies, ### Verdict.
Each ### Findings item includes severity (Blocker / Major / Minor), doc path, quoted stale claim, code evidence, and recommended edit. Redundancy findings replace the stale claim and code evidence with the duplicated claim (quoted once; both passages for a qualifier-beside case) and every location where it appears.
Distinction
/hyperclaude:hyper-docs-review— Codex critiques documentation accuracy (this skill)/hyperclaude:hyper-docs-sync— Claude updates docs to match code (sister skill)/hyperclaude:hyper-code-review— Codex critiques code diffs/hyperclaude:hyper-plan-review— Codex critiques implementation plans
Scope is STRICT: accuracy / drift / completeness / broken links / cross-doc inconsistencies / redundancy (in-doc duplicated or appended-beside claims — reported Minor; deliberate cross-doc propagation exempt). NOT style or prose quality — prose polish is a direct edit; the documenter agent makes accuracy edits only.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |