refresh-agent-docs

Refresh Agent Docs

Keeps .agents/docs/ honest. Each DOC.md and <SUBTOPIC>.md carries YAML frontmatter (last_verified, optional upstream_commit, sources); this skill re-verifies, applies fixes, and bumps the date.

Pair with gather-agent-docs (seed entries, deepen on request) and use-agent-docs (read them).

Scope

• Default: every entry in INDEX.md — every *.md under each topic's directory.
• Topic-targeted: when the user names slugs ("refresh gemini-cli", "refresh cloud-run and firebase"), refresh every *.md in those directories.
• Subtopic-targeted: when the user names a specific file ("refresh gemini-cli/hooks"), refresh only that file and re-bump the topic's INDEX.md date to the new oldest.
• No-op if .agents/docs/INDEX.md does not exist — propose gather-agent-docs instead.

Smart refresh

Before re-fetching upstream content, try the cheap paths in order. The richer the page's frontmatter, the more refreshes short-circuit.

1. Commit-pin shortcut. If upstream_commit is set and matches upstream HEAD (e.g. via the repo URL's HEAD SHA), the page is verified by definition. Bump last_verified, mark unchanged, done.
2. Changelog shortcut. Fetch sources.changelog (or sources.release) and filter entries dated after last_verified. None matching → bump last_verified, mark unchanged, done.
3. Link-rot scan. HEAD-check every URL in the Documentation map. All resolve, no nav drift, no T2 snippet sources changed → bump and done.
4. Targeted re-verify. Some changelog entries touch surfaces in the map (or some links 404) → re-fetch the topic's nav source to detect renamed/removed/added pages, and re-fetch each affected T2 snippet's _Source: …_ page.
5. Full re-fetch. No upstream_commit, no changelog, smart paths inconclusive → re-fetch the topic's nav source and walk every captured T2 snippet.

Per-file workflow

For each *.md in scope (DOC.md plus any subtopic files):

1. Read the local page — frontmatter, summary, key concepts, Documentation map, optional Patterns.
2. Run smart refresh to pick the path. For dead links (404, moved), search for the current equivalent and substitute it. If no replacement exists, drop the entry and note the gap in the report.
3. Diff and fix when re-verifying:
   • URL in the map moved → update.
   • Page renamed in upstream nav → update title and one-line hook.
   • New page in upstream nav covering a meaningful surface → add to map.
   • Page removed upstream → drop entry.
   • Captured T2 snippet drifted → update or remove. Add a new snippet only on user request (deepen).
   • Section restructured upstream → mirror the new grouping.
4. Bump the frontmatter last_verified to today and refresh upstream_commit when applicable. After all of a topic's files are processed, set INDEX.md's [YYYY-MM-DD] for that topic — and INDEX.md's own last_verified frontmatter — to the oldest last_verified among that topic's files.
5. Stale banner. When a page can't be re-verified this session (upstream unreachable, login-walled, rate-limited) or its last_verified is more than 6 months old after this run, insert at the top of the body (just below the frontmatter): > ⚠ Stale (verified YYYY-MM-DD). Confirm captured details upstream before acting. Remove the banner automatically on the next successful re-verify.
6. Record the outcome for the report.