Docset refresh

Overview

Bring the full documentation set current in one pass. This skill is an orchestrator: it does not write architecture, install, usage, README.md, or AGENTS.md content directly. It invokes the skill that owns each of those, in an order where later skills can link into what earlier skills produced, then audits the remaining docs/ files no per-doc skill owns.

Owned-doc routing

Each artifact has one owning skill. Dependencies follow ownership, so independent owners run together:

• arch-docs -> docs/CODE_ARCHITECTURE.md, docs/FILE_STRUCTURE.md
• setup-install-usage-docs -> docs/USAGE.md, docs/INSTALL.md
• see-also-docs -> docs/RELATED_PROJECTS.md
• news-release-docs -> docs/RELEASE_HISTORY.md, docs/NEWS.md
• readme-docs -> README.md (sole owner; links the core docs by convention, reserves the screenshot block)
• screenshot-docs -> docs/screenshots/ WebP screenshots at quality 90 and the managed screenshot block inside README.md and docs/
• agents-md-fixer -> AGENTS.md (bare-path pointers into docs/*.md)

readme-docs owns all of README.md, so the doc producers create only their own docs/ files and readme-docs writes every README link. With one owner per artifact, the producers carry no write conflict and run together.

Dispatch by dependency edges, not a fixed barrier, so each owner starts as early as its inputs allow:

• Start immediately, no dependencies (one concurrent batch): arch-docs, setup-install-usage-docs, see-also-docs, news-release-docs, readme-docs, and the remaining-docs audit (step 3). Each owns separate files, so they carry no write conflict. readme-docs links the core docs (CODE_ARCHITECTURE, FILE_STRUCTURE, INSTALL, USAGE) by convention, so it runs alongside their producers; the final Markdown link check confirms the files exist.
• screenshot-docs <- readme-docs: start as soon as readme-docs has reserved the screenshot block. It does not depend on the other producers, so it runs concurrently with the still-running batch (including the slow see-also-docs) instead of waiting behind it.
• agents-md-fixer <- the doc producers and audit outputs: start once the docs/*.md files it links exist. It points AGENTS.md at created paths, not prose, so it waits for file existence only, not content quality.

see-also-docs is the likely long pole: its bounded web discovery (search, fetch, and package/repo metadata with rate-limit sleeps) is network-bound and may dominate wall time. The dependency-edge model matters because it lets the readme-docs -> screenshot-docs path finish in parallel rather than stall behind that network-bound producer. Keep discovery bounded; do not gate the rest of the refresh on it.

README links for conditional docs

readme-docs links the core docs above by convention. Conditional docs (for example docs/TROUBLESHOOTING.md, created only when evidence supports them) stay discoverable through docs/ and AGENTS.md. A conditional doc created in this same run is not guaranteed a README link in the same run; link it on a later pass when it is present.

Workflow

1. Read the rules and inventory
   • Read AGENTS.md, docs/REPO_STYLE.md, and docs/MARKDOWN_STYLE.md.
   • List docs/ contents and root docs (AGENTS.md, README.md, LICENSE.<SPDX>).
2. Dispatch the per-doc skills by dependency edges
   • Follow the ownership and dependency edges above. Start independent owners and the remaining-docs audit together; release downstream owners when their input exists.
   • screenshot-docs runs after README prose exists. When no app window or display is available, it adds a Known-gaps line to the report, leaves existing screenshots and the managed block in place, leaves both block sentinels for the next run, and agents-md-fixer still proceeds.
   • Let each skill decide whether its docs need creation or refresh; each skill owns its own content.
3. Audit the remaining docs (this skill's direct responsibility)
   • Each file below is an independent audit target. This list is the source of truth for which files the audit covers.
   • For each below, create or update a doc only when repo evidence supports at least one useful section beyond its title, intro, and any known gaps. When evidence is thin, record the doc under Known gaps in the step-8 report and write no file.
     • docs/CHANGELOG.md
     • docs/ROADMAP.md
     • docs/TODO.md
     • docs/TROUBLESHOOTING.md
     • docs/COOKBOOK.md, docs/DEVELOPMENT.md, docs/FAQ.md (only when evidence exists)
   • Choose one file I/O doc unless more are clearly needed: docs/INPUT_FORMATS.md, docs/OUTPUT_FORMATS.md, or docs/FILE_FORMATS.md. Add docs/YAML_FILE_FORMAT.md only when YAML is a real interface surface.
4. Check centrally maintained docs
   • Verify presence and exactness only. Do not edit content.
     • docs/AUTHORS.md
     • docs/MARKDOWN_STYLE.md
     • docs/PYTHON_STYLE.md
     • docs/REPO_STYLE.md
5. Flag docs that should not exist
   • If present, recommend relocation or deletion:
     • CONTRIBUTING.md (prefer docs/DEVELOPMENT.md)
     • CODE_OF_CONDUCT.md
     • COMMUNITY.md
     • Issue/PR templates
     • SECURITY.md
6. Apply naming and style rules to anything this skill writes directly
   • Use ALL CAPS with underscores under docs/.
   • Keep links relative and descriptive.
   • Use present tense, short bullets, and avoid speculation.
7. Update changelog
   • Update docs/CHANGELOG.md directly.
8. Provide a short report
   • Per-doc skills run: which of the per-doc owners ran and what each reported.
   • Created: list new docs.
   • Updated: list updated docs.
   • Flagged: list docs to relocate or delete.
   • Known gaps: list verification tasks only.

Content shape for audited docs

When evidence supports a doc this skill writes directly (step 3), follow this shape:

• Title in sentence case.
• One paragraph describing scope and audience.
• At least one substantive section grounded in repo evidence, with 2 to 6 bullets each, one idea per bullet.

When not to create a file: when the only content would be a title, an intro, and a known-gaps list, write no file. Record the doc under Known gaps in the step-8 report so the gap stays visible and the owning skill can create the doc once evidence supports it.