| name | docs-review |
| description | Review and update the JarHC project documentation under website/docs/. Use this whenever the user wants to review documentation, update or rewrite a docs page, check whether documentation is stale or out of date relative to the code, verify that a report-section page still matches its analyzer, or add a new documentation page. Also use it after changing source code (analyzers, command line options, dependencies) that the documentation describes, to find and refresh the affected pages. It can run a freshness check that flags pages whose sources changed after their last review.
|
Documentation review
This skill helps keep the JarHC documentation under website/docs/ accurate and in a
consistent style. It does three things: find pages that may be out of date,
update a page against its sources, and scaffold a new page.
Conventions live in AGENTS.md
All documentation conventions (tone, the report-page skeleton, the column
documentation style, and the front-matter schema for sources,
last_reviewed, and description) are defined in the repository's AGENTS.md, under the
"Documentation" section. Read it first and follow it. Do not restate those rules
here; AGENTS.md is the single source of truth so the two cannot drift apart.
Find pages that may be stale
Run the bundled script. It reports pages whose listed sources have a newer git
commit date than the page's last_reviewed, plus missing sources and sources
with no git history:
.agents/skills/docs-review/scripts/check-docs-freshness.sh
The script works from the git repository root and scans website/docs/ by default; pass
a different directory as the first argument if needed. A non-zero exit code means
at least one page needs attention. "Stale" only means a source changed after the
review date, not that the change was necessarily doc-relevant, so each finding
still needs a human-style judgement during the update step.
Update a page
For each page that needs attention:
- Read the page and the files in its
sources front matter.
- Verify every statement on the page against the source. For a report-section
page, the source is the analyzer (for example
BlacklistAnalyzer for the
Blacklist section); describe what it actually produces, including special
value markers and column order.
- Apply the conventions from
AGENTS.md (tone, structure, column style).
- If the source genuinely changed what the page must say, update the prose. If
the page is already correct, leave the prose unchanged.
- Either way, set
last_reviewed to today's date.
Add a new report-section page
Follow the report-page skeleton defined in AGENTS.md. Verify the column names
and behavior against the analyzer, and add the analyzer (and any resource that
drives its output) to the page's sources front matter. Also give the page a
description (see AGENTS.md).
Validate the build
After updating or adding pages, build the documentation in strict mode to catch
broken internal links, invalid anchors, and pages missing from the navigation.
Strict mode turns MkDocs' link and navigation validation warnings into errors:
docker run --rm -v "$PWD/website":/docs squidfunk/mkdocs-material build --strict
A non-zero exit code means there is a link or navigation problem to fix.
This complements the freshness check: the freshness check finds out-of-date
pages, while the strict build verifies the documentation is internally consistent.
