Stats
Actions
Tags
From Flagrare
Pre-commit audit that diffs staged changes against README, decision logs, public API, doc comments, release notes, and tests to surface and auto-fix documentation drift.
How this skill is triggered — by the user, by Claude, or both
Slash command
/flagrare:staleness-auditThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
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.
git diff --staged --stat — what's about to be committedgit diff --staged — the actual hunks (only read the ones you need)git status — what's unstaged or untracked that might also be driftWork 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).
The README.md is the project's storefront. After every commit, ask:
## 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.- [ ] 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.If the project has a decision log (ADRs in docs/decisions/, RFCs, or equivalent), check:
Status: says "Accepted" but is actually superseded by a later one — update status on both.If the project has no decision log, skip this check.
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:
src/index.ts (or the barrel specified in package.json#exports)<package>/__init__.pysrc/lib.rs (pub use re-exports)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.
For the project's documentation format, spot-check staged source files:
export class / function / interface / type / const without a leading /** … */?pub fn / pub struct / pub trait without /// doc comments?Flag any new public symbol without documentation. Flag existing doc comments that still say TODO or @todo.
If the commit touches source files, ask: is this user-observable?
.changeset/*.md file (run pnpm changeset or npx changeset to draft)changelog.d/ fragmentCHANGELOG.mdIf the project has a CONTRIBUTING.md (or equivalent), after any commit that adds or removes tooling:
package.json, Cargo.toml, pyproject.toml, go.mod, etc.).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.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.).
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.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:
/flagrare:research-catalog invoked before the synthesis was returned? If not, run it now before committing.If no external research was conducted this session, skip this check.
If the project uses a ~/.claude/projects/<path>/memory/ directory with [[name]] crosslinks, and this commit touches docs or memory files, check:
[[some-name]] resolves to a file some-name.md in the memory directory for this project.MEMORY.md index has an entry for every .md file (other than itself).To find the memory path: derive it from pwd — the project memory dir is ~/.claude/projects/<pwd-with-slashes-replaced-by-dashes>/memory/. If the directory doesn't exist, skip this check.
Before invoking git commit, verify the message matches the project's commit convention. Check the recent git log to identify what convention is in use, then verify the new message follows it. Common conventions:
✨ feat(scope): subjectfeat(scope): descriptionRegardless of convention: subject should be ≤ 72 chars; body explains why when the change is non-obvious.
If this commit touches CI/CD config or dependency management config, verify that any automated committers (Renovate, Dependabot, release bots, merge bots) produce messages that match the project's commit convention.
Check the relevant config files for the project's CI platform:
.github/workflows/, .github/renovate.json, .github/dependabot.yml.gitlab-ci.yml, .gitlab/The rule of thumb: if a tool can push a commit, its message template must satisfy the project's commitlint rules — or the merge strategy must ensure a manually-written squash message.
Whenever this commit touches CI config files:
When you're done, give the user a concise audit line for each check — ✓ if clean, → fixed: … if you applied a mechanical fix, ⚠ needs decision: … if it's a judgement call. Don't pad with checks that found nothing.
If any check found a real issue, fix it before committing unless the user explicitly opted out of fixing this round.
/flagrare:write-docs for documentation driftIf any of checks 1, 2, 4, 5, or 6 surfaced drift (README staleness, decision log issues, missing doc comments, missing release notes, contributor guide hygiene), invoke /flagrare:write-docs to rewrite the affected sections. Pass it the specific files and the nature of the drift so it can apply craft-level prose rather than mechanical patching.
Skip this step when:
docs/style-guide.md, WRITING.md), or user instructions in CLAUDE.md / memory that specify how that file should be written. When project-specific or user-specific writing rules exist, follow those directly instead of delegating to /flagrare:write-docs.If neither exception applies and the fix requires rewriting prose, descriptions, or explanations, /flagrare:write-docs owns the quality of that output.
/flagrare:release-checkOnce the commit lands, invoke /flagrare:release-check immediately. That skill answers the post-commit question "is a release due?" and drafts a value-focused CHANGELOG entry when one is. Cheap when nothing's pending.
Project rot starts when README says "pre-alpha" three months after v1.0, when the decision log shows choices nobody remembers the reasons for, when the roadmap shows boxes already ticked elsewhere. Catching drift at commit time costs ~30 seconds. Catching it at "why is our README lying" time costs hours and credibility.
npx claudepluginhub flagrare/agent-skills --plugin flagrareProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.