/staleness-audit

name: staleness-audit
description: Pre-commit audit. Invoke before every git commit. Diffs the staged change against the repo's "canaries" (README, decision log, roadmap, public API, doc comments, release notes, test discipline) and surfaces anything that's drifted out of sync. Updates the obvious drifts in place; flags judgement calls for the operator.

Staleness audit

Run this before every commit. The goal is simple: **a commit should leave the docs, types, and roadmap in a state consistent with the code it ships**. Drift between code and its surrounding narrative is how projects rot.

Don't be lazy, actually run the checks. Each one is a `grep` or a `diff`. The whole audit should take under 30 seconds.

How to invoke

You (the model) invoke this skill yourself, before staging the final commit. The rule: *every commit goes through this checklist*. If you're amending or splitting commits, run it per commit.

Inputs

• `git diff --staged --stat`, what's about to be committed
• `git diff --staged`, the actual hunks (only read the ones you need)
• `git status`, what's unstaged or untracked that might also be drift
• The repo working tree for the canary files listed below

Procedure

Work through the checks in order. For each finding, either **fix it now** (if the fix is mechanical and in scope) or **note it explicitly** in the commit body / the response to the user (if it's a judgement call).

1. README staleness

The `README.md` is the project's storefront. After every commit, ask:

• **Status line**: does `## Status` (or the equivalent line) still match reality? Words like "pre-alpha", "bootstrapping", "WIP", "coming soon", "not yet implemented" need to age out as features ship. If this commit moves the needle, update the status text.
• **Roadmap checkboxes**: `- [ ] X` for things that *just shipped* in this commit (or earlier ones not yet ticked) should become `- [x] X`. Conversely, anything ticked that's been ripped out needs to be re-opened or removed.
• **Code examples**: if a public-API signature changed, do the README code blocks still compile and reflect the new shape? Grep the README for the renamed/removed identifier.
• **Badge accuracy**: if a CI workflow or license changed, the badges still point at the right thing.

2. Decision log integrity

If the project has a decision log (ADRs in `docs/decisions/`, RFCs, or equivalent), check:

• Any new decision file that isn't in the index. Add it.
• Any decision whose `Status:` says "Accepted" but is actually superseded by a later one, update status on both.
• Cross-references that point at filenames that no longer exist.

If the project has no decision log, skip this check.

3. Public API sync

If the project has a single public entry point, verify exports are in sync after every commit touching source files. The entry point varies by language:

• **TypeScript:** `src/index.ts` (or the barrel specified in `package.json#exports`)
• **Python:** `<package>/__init__.py`
• **Rust:** `src/lib.rs` (`pub use` re-exports)
• **Go:** exported symbols in the package's public files

For every export newly added in non-entry source files, is it re-exported from the entry point? For every removed export, is the entry point cleaned up?

If the project has no single entry point (e.g. a CLI tool, not a library), skip or adapt this check.

4. Doc comment completeness on public symbols

For the project's documentation format, spot-check staged source files:

• **TypeScript:** any new `export class / function / interface / type / const` without a leading `/** … */`?
• **Python:** any new public function/class without a docstring?
• **Rust:** any new `pub fn / pub struct / pub trait` without `///` doc comments?
• **Other:** apply the language's equivalent convention.

Flag any new public symbol without documentation. Flag existing doc comments that still say `TODO` or `@todo`.

5. Release note for user-facing changes

If the commit touches source files, ask: is this user-observable?

• If yes, verify it's captured in the project's changelog mechanism:
• **Changesets:** a `.changeset/*.md` file (run `pnpm changeset` or `npx changeset` to draft)
• **towncrier:** a `changelog.d/` fragment
• **Manual CHANGELOG:** a new entry in `CHANGELOG.md`
• **Conventional commits:** the commit message itself is the record, verify it's descriptive enough
• If no (pure internal refactor / test / docs / tooling), no release note is needed, but note that explicitly.

6. Contributor guide hygiene

If the project has a `CONTRIBUTING.md` (or equivalent), after any commit that adds or removes tooling:

• Search for references to tools that are no longer in the project's dependency manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, etc.).
• If a workflow changed (CI job, hook, script), make sure the contributor guide reflects it.

7. Test name discipline

Test names should describe **behaviour**, not method names. Grep newly added/changed test files for:

• `it("works")`, `test("test 1")`, `it("should work correctly")`, `it("returns the value")`, vague or method-centric. Flag.
• Good names: `it("rejects an out-of-range index with a RangeError carrying the attempted value")`.

This applies regardless of framework (Jest, Vitest, pytest, RSpec, Go test, etc.).

8. Stale markers in new code

Grep the staged diff for tokens that shouldn't ship:

• `TODO`, `FIXME`, `XXX`, `HACK`, `@todo`, fine if they reference an issue (`TODO(#42)`); not fine if naked.
• `console.log`, `debugger`, `.only`, `.skip` in test files.
• Leftover lint-suppression comments without an explanation.

9. Research catalog

If external research was conducted during this session (WebFetch, WebSearch, or Explore-agent fetches of URLs outside the repo) and the findings informed this commit:

• Was `/flagrare:research-catalog` invoked before the synthesis was returned? If not, run it now before committing.
• Does the consuming artifact (ADR