check-third-party-docs

Check third-party docs

We vendor copies of the upstream docs for the external tools our skills wrap (e.g. the MacWhisper mw CLI behind work-with-media:macwhisper-cli). This skill re-fetches those upstream docs, shows what changed since the last cache, and proposes edits to the local skills/docs that the change affects — so our wrapper docs never silently drift behind the tool.

Cached docs live in docs/third-party/cached/*.md. Each is self-describing — its frontmatter names the upstream source URL, when it was last_updated, and the local skills/docs it informs (related). There is no separate manifest; the cache dir is the registry. Run everything from the repo root.

Frontmatter contract (every cached doc)

---
source: <upstream URL>                     # what to re-fetch
cached_from: research-tools:fetch-docs --md # how it was fetched (for a matching refetch)
last_updated: <YYYY-MM-DD>                  # bumped on every refresh
related:                                    # what this doc informs, so review is mechanical
  - work-with-media:macwhisper-cli          # a skill (plugin:skill) …
  # - plugins/<plugin>/README.md            # … or an explicit repo-relative doc path
---

Refresh workflow

Do this for each cached doc (all of them, or the one the user named). The order matters — overwrite the cached file before diffing so git diff naturally shows the committed (old upstream) version against the working-tree (new) version.

1. Read the cached doc's frontmatter to get its source, cached_from, and related.

2. Re-fetch the source with the research-tools:fetch-docs skill, matching cached_from (use --md when the cached copy is markdown). It writes the fresh copy to a /tmp/fetch-docs-*.md path and returns that path. Pass --ttl=0 to force a live refetch and bypass fetch-docs' 24h cache.

3. Overwrite the cached file — replace its body with the fresh /tmp fetch and refresh the frontmatter: keep source/cached_from/related, bump last_updated to today (date +%F). Store the fetch body exactly as fetched — never hand-clean it — so the next refresh diffs against the same pipeline output instead of fighting your edits. Example, run from the repo root: