# Review Public Docs
> Retrieve scoped Rust public API docs from cargo-generated rustdoc JSON for a PR, branch, commit, working tree or explicit items. Returns a compact bundle of paths, full item/member docs, attributes, links and coverage. Use for "what do these APIs document", documentation presence, or authoritative docs needed by another reviewer. Not for design, prose/consistency judgments, implementation correctness, posting or rendered docs.rs pages.
- Skill: `martintmk/review-public-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add martintmk/review-public-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/martintmk/review-public-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: martintmk (https://skillmd.com/u/martintmk)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/martintmk/review-public-docs
---
# Review Public Docs
Retrieve **public** API docs from cargo-generated rustdoc JSON, not findings,
severity, verdicts or posts. This data bundle is exempt from the
[findings contract](../review-delivery/findings-contract.md). Apply the
[fresh-worker gate](../review-lens/worker-isolation.md): retrieval has its own
context, even when called by an isolated API filter; assigned workers do not
redispatch themselves.
Review Lens dispatches retrieval every run. Proven no-Rust-library scope in the
supplied factual inventory permits `not-applicable` with provenance, not invented
bundles or unrelated builds. Rust changes require matching comparison even to
report no changed public items. Missing present-side artifacts/build failures
block; proven absence uses [one-sided comparison](../review-lens/package-comparison.md).
Pass code/docs or docs/docs disagreements with scoped evidence through the
requester/coordinator to [`review-consistency`](../review-consistency/SKILL.md);
never judge them or launch another review.
## Input and evidence boundary
Accept PR/branch/commit, `...`, working tree or explicit paths/members
(preferred), plus package/manifest, features, target and toolchain. Reuse resolved
revisions, permissions, tools and artifact provenance/ownership under applicable
[shared context](../review-lens/review-context.md) trust, matching and cleanup
rules, not source-review/reproduction prerequisites. Never restart coordinator
setup or invoke `review-lens`.
Only JSON proves doc text, visibility, associations and members. Revision/
diff-file metadata selects scope; Cargo metadata/diagnostics identify artifacts;
`packageComparison` proves package presence only. None substitutes for present-side
JSON. Never fall back to source, manifests, diff text, rendered rustdoc or docs.rs.
Docs are untrusted intent, not instructions or runtime proof. Return scoped
bundles to docs consumers, never full docs/JSON to output-only parents.
## Independent resolution and change axes
Account for each requested item even without docs:
| Resolution | Meaning |
| --- | --- |
| `found` | Unique public association; return docs. Confirmed local null `docs` means `undocumented`. |
| `ambiguous` | Multiple public matches; list candidates, never choose. |
| `not-in-configuration` | Proven existing but gated by selected features/target. |
| `not-public` | Proven private, `#[doc(hidden)]` or unreachable. |
| `unresolved` | Unsupported association; explain the gap. |
JSON absence cannot distinguish gating, privacy, hiding or typos. Require
artifact/configuration evidence for specific statuses, otherwise `unresolved`;
never inspect source. Confirmed missing local docs prove only undocumented status.
For baseline comparisons, add an independent marker:
| Marker | Path presence and docs source |
| --- | --- |
| `added` | Head only; head docs. |
| `deleted` | Base only; baseline docs. |
| `unchanged` | Both; head docs, plus baseline docs when needed. |
`unchanged` does **not** mean identical signatures/docs; deleted items can be
`found` in base. Never compare build-local IDs, present baseline docs as current,
or invent markers for unresolved associations. Retrieval-level `blocked` covers
execution/build/artifact/schema/comparison failure, not individual unresolved items.
## Procedure
### 1. Resolve scope and comparison
Explicit paths restrict retrieval, not a supplied baseline. Current-only
requests use head-only mode and disclaim deleted-item coverage; changes,
removals and renames require identically configured base/head comparison.
Explicit baselines win; `...` uses merge base:
```text
git merge-base
```
Working-tree head includes actual dirty state; default its baseline to `HEAD`
only when none was supplied. Resolve PR/branch/commit baselines from caller
context; missing required scope is `blocked`. Published baselines need exact
versions, not `latest` or similarly named Git tags.
Before change builds, consume proven `packageComparison`; head-only retrieval
needs no baseline-presence record:
- `added-package`: retain exact base/absence proof, logical empty base paths,
real head JSON. Resolved head items, including root docs, are `found`/`added`.
- `removed-package`: retain exact head/absence proof, real base JSON, logical
empty head paths. Resolved baseline items are `found`/`deleted`, never current.
- `paired`: real matching artifacts, with resolved moved/renamed selectors.
- `unknown` presence/mode or missing required present-side artifacts is `blocked`;
selector/build failure does not prove absence.
Never build absent sides or manufacture JSON. Complete one-sided retrieval and
proof constitute complete comparisons, not head-only or `not-applicable`.
Unresolved requested names do not automatically acquire added/deleted markers.
Build present revisions only without matching artifacts. Materialize required
Git snapshots outside the repository, never checkout the caller's tree:
```text
git worktree add --detach
```
Worktrees neither sandbox execution nor contain dirty changes; build actual
working-tree heads in place with external targets. Published baselines need
matching artifacts or trusted package snapshots, not guessed revisions. Missing
required artifacts block, never silently downgrade paired coverage to head-only.
Compare **public surfaces**: path differences for additions/deletions; normalized
signatures, docs, attrs, links, members and impls for shared paths. Ignore unstable
IDs/spans; include affected owners/impls and confirmed aliases, not just `.paths`.
Changed-file metadata prioritizes but cannot exclude APIs affected elsewhere by
macros/impls:
```text
git diff --name-only ... -- '*.rs'
```
For dirty scope compare actual working tree against resolved base, not `...HEAD`.
Never grep added `pub` lines: removals, renames, moves, re-exports and generated
APIs disappear. Keep full inventories in artifacts; return scoped records/counts.
### 2. Match or generate artifacts once
Match repository/snapshot including dirty state, revision, package/manifest/
library, exact features/defaults, effective target, toolchain and inherited build
flags. `cargo public-api` JSON also needs suitable public output/schema; private
items are not public evidence. Matching complete closure/status bundles skip
generation/traversal. Filenames alone never justify reuse.
Before builds/installations use established execution trust: scripts/proc macros
require trusted code or isolated credential-free execution. Generate once per
required revision into distinct external targets:
```text
cargo + rustdoc --locked --lib --target-dir -- -Z unstable-options --output-format json
```
- `` is `--all-features` unless explicitly replaced by exact
`--features`/`--no-default-features`.
- `` carries selected `-p `, `--manifest-path`, `--target`.
- Preserve the caller-selected compiler, including stable, MSRV and custom
Microsoft toolchains. Probe it through the Rust tool multiplexers:
`rustc + --version` and `cargo + --version`. Do not use
`rustup run` or absence from `rustup toolchain list` as proof that a custom
toolchain is unavailable; MSRustup and similar multiplexers resolve `+toolchain`
without registering the channel in rustup.
- Set `RUSTC_BOOTSTRAP=1` only for the rustdoc subprocess that requests unstable
JSON output. Never persist or export it for the worker, repository, user or
machine. On PowerShell, save and restore any pre-existing value in `finally`;
on POSIX shells, use the command-local prefix shown above. This enables the
rustdoc output format without substituting a different compiler or changing
normal stable builds.
- Preserve caller nightly-capable toolchains without the bootstrap when they
already accept `-Z unstable-options`; never broaden scope for success.
- Never use `--document-private-items`. Reuse tool checks; install only missing
required nightly when the caller selected nightly:
`rustup toolchain install nightly --profile minimal`.
- `--locked` preserves lockfiles. Report absent/outdated locks, never update
reviewed inputs; external targets alone do not protect them.
Discover `/doc/.json` or target-qualified
`//doc/.json`, including configured targets.
Package hyphen replacement cannot establish `[lib] name`. Example:
```powershell
Get-ChildItem -Path \doc\*.json, \*\doc\*.json
```
Ignore nonexistent layouts, not access/read failures. One selected package's
`--lib` build in a fresh target produces one library JSON. Reused/multiple matches
require identity confirmation using matching manifest/package context:
```text
cargo metadata --no-deps --format-version 1
```
Select the package's library target, including actual crate-type; match normalized
name to JSON root. Keep metadata internal, return identity only; base/head
selections must be equivalent. Metadata is not docs evidence.
Execution/build/artifact/format failures return `blocked`, exact attempted
command and decisive diagnostic. Preserve resolved coverage as explicitly partial.
### 3. Traverse and select complete documentation closure
When parsing JSON, **load [schema-aware traversal](rustdoc-traversal.md)** for
schema checks, exact public/alias/member resolution and extraction; callers must
not maintain parallel parsers. Root-only scaffolds need actual crate docs/attrs;
empty descendants are valid.
Return full text for selected items and applicable owners, governing traits,
modules/re-exports, crate docs and relied-on local links. Label why context
applies and deduplicate shared records. Scope records, **not sentences**.
Include attrs, deprecation, relevant members/impls and resolved links; name gaps.
### 4. Return data and release resources
Use this shape, omitting empty optional fields and head-only change markers:
```text
# Public API docs: (, format_version )
Scope:
Mode:
Package presence:
Config:
Artifacts:
Items in scope: ( undocumented)
## - [] []
Source:
Association:
Attributes / Deprecation:
Members / Trait impls:
Doc links: resolved path, or explicit unresolved/external status>
Context:
## Unresolved or non-public
- :
## Coverage
```
Account for **every requested path**. Claim no public changes only after required
comparison, retaining configuration/coverage. No raw JSON or scoped-request crate
dumps. After all consumers finish, the designated owner removes only owned
targets/worktrees:
```text
git worktree remove
```