agentleFS
zeikarzeikar/hyperclaude/skills/hyper-docs-review/SKILL.md

hyper-docs-review

Skill5 starsChanged 48 days agoMITView on GitHub

Use 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).

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After hyper-docs-sync has edited docs and you want a Codex accuracy gate.

    line 13
  2. Very specific:

    When Group 3 is '--resume' (truthy) and Group 4 is undefined, treat as --resume auto.

    line 39
  3. Distinctive:

    If the argument doesn't match the regex, ask the user to clarify and stop.

    line 52
  4. Very specific:

    Use the Bash tool with run_in_background: true (invocation mode: ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md).

    line 73
  5. Very specific:

    If --diff-base <ref> was matched (Group 2), append --diff-base <ref> to the argv.

    line 86

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-sync has 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 to docs/. Negative lookahead per-token prevents matching --diff-base or --resume as 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 — reviews docs/, 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 — reviews docs/, 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 from auto
  • /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-path files, 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 tokensBridge 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-path files, or a smaller subdirectory)
  • no .md files in <path> → tell user the directory has no top-level markdown
  • git diff exceeds 500KB → tell user to use a closer --diff-base ref or omit it

Output contract

Docs-review files have YAML frontmatter:

  • mode: docs-review
  • template-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-version
  • codex-version
  • docs-target (a JSON STRING of the dir path in --docs-dir mode, or a JSON ARRAY of file paths in --docs-path list mode)
  • Optional diff-base (when --diff-base was 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.