Documentation Freshness Rules

Purpose

Use these rules when reviewing or refreshing documentation for a public AI workflow registry. The goal is to stop stale docs, stale examples, broken source links, and old compatibility claims from looking current just because they still render.

Freshness is not only about dates. A source can be old but stable, or new but unverified. Review whether the registry entry still matches the source of truth users will rely on today.

Freshness Metadata

Every public registry entry should make current-state claims reviewable.

1. Reviewed date. Record when the entry or source claim was last checked.
2. Reviewed version. Record package, app, API, spec, framework, model, or docs version when the source provides one.
3. Canonical source URL. Prefer stable docs, repo, package, release, or standard URLs over blog posts, announcement pages, short links, and redirects.
4. Source type. Distinguish docs, README, package metadata, changelog, release note, standard, policy page, or maintainer review.
5. Update trigger. Say what should cause a refresh: new major version, package deprecation, API change, pricing change, policy update, broken link, or safety/privacy change.
6. Known unknowns. If current behavior cannot be verified, say so instead of presenting the entry as current.

Review Rules

• Verify every source URL still resolves to the expected canonical page.
• Remove tracking parameters, campaign fragments, and stale redirect targets.
• Re-check install commands against the current package manager, runtime, and platform requirements.
• Re-check examples when APIs, auth flows, command flags, environment variables, model names, hosted plans, or file paths change.
• Treat pricing, plan names, privacy behavior, telemetry, support level, license, and production readiness as volatile claims.
• Keep old release notes as history, not as evidence of current behavior.
• Do not edit generated registry artifacts unless the repository explicitly asks contributors to do so.

Stable Source Rules

Stable URLs make future review easier.

• Prefer documentation pages that remain valid across versions.
• Use versioned pages when the entry depends on version-specific behavior.
• Prefer canonical repository, package, or standard pages over search result pages, CDN mirrors, screenshots, social posts, and copied snippets.
• Keep one source of truth for each claim; do not cite multiple weak pages when one canonical source is available.
• If a URL redirects, verify the destination still supports the claim.
• If a source page is removed, archive status can explain history, but a current registry entry needs a current source or a clear stale/deprecated label.

Stale Claim Rules

Request edits or block merge when an entry:

• says "latest," "current," "new," "official," "production-ready," "secure," "free," "open source," or "supported" without current source evidence;
• names an old package version but describes current behavior;
• copies install commands from a README that changed runtime or permission requirements;
• links to examples that no longer match source docs;
• describes hosted retention, telemetry, pricing, or account behavior from an old plan page;
• keeps a safety or privacy note after the underlying tool changed execution surface, permissions, or data movement.

Reviewer Checklist

• {"task": "Sources resolve", "description": "All source URLs resolve to expected canonical pages without unwanted redirects or tracking parameters"}
• {"task": "Reviewed date", "description": "The entry records when the source-backed claims were last checked"}
• {"task": "Version known", "description": "Package, API, framework, spec, model, or docs version is recorded when relevant"}
• {"task": "Volatile claims checked", "description": "Install, pricing, support, privacy, safety, compatibility, and production-readiness claims have current evidence"}
• {"task": "Examples match", "description": "Commands, config snippets, screenshots, and examples still match current source behavior"}
• {"task": "Update trigger noted", "description": "Future reviewers can tell what event should cause the entry to be refreshed"}

Do Not Merge When

• source URLs are broken, redirect to unrelated pages, or only work through a private account;
• freshness depends on screenshots, copied terminal output, AI summaries, or old announcement posts instead of canonical source pages;
• volatile claims are written as timeless facts;
• examples use deprecated commands, old package names, removed APIs, or unsupported runtime versions;
• privacy, safety, license, pricing, or support claims are stale or unsourced;
• the PR refreshes generated registry artifacts instead of the raw source entry.

Troubleshooting

• A source URL works but redirects: update the entry to the canonical destination if it still supports the claim.
• The docs have no visible date: record the date you reviewed the page and the version or release context you could verify.
• The package changed but docs did not: mark the claim as uncertain and ask for maintainer evidence or a safer wording.
• The current docs conflict with an old entry: trust the current canonical docs, then preserve history only when it matters to migration.
• The entry needs generated output: update the raw source file and leave generated artifacts to the maintainer workflow.

Duplicate Check

Checked existing rules, guides, collections, hooks, skills, MCP entries, statuslines, registry quality code, submission validation code, and recent PRs for documentation freshness rules, stale source review, source freshness, last-reviewed metadata, registry freshness, versioned docs, and public registry update policy.

Adjacent content includes a documentation coverage hook and registry quality code that tracks source freshness. This rules entry is distinct because it gives portable do/don't behavior for contributors and reviewers deciding whether a public registry entry's documentation and source claims are fresh enough to merge.

Source Mapping

Each freshness rule below traces to an established documentation-maintenance practice. Use this table to ground a review decision in a public source rather than personal preference.

References

• Write the Docs, Documentation Principles: https://www.writethedocs.org/guide/writing/docs-principles/
• Write the Docs, Docs as Code: https://www.writethedocs.org/guide/docs-as-code/
• Keep a Changelog 1.1.0: https://keepachangelog.com/en/1.1.0/

• Source repositorygithub.com 2026-07-19T11:20:19-07:00
• Documentationwritethedocs.org
• Submitted by MkDev112026-06-04