doc-freshness-reverse-lint

Detect stale normative guidance in project docs after memory-file rules change.

1|Updated Apr 16, 2026
One-click install
npx skills add https://github.com/wan-huiyan/claude-ecosystem-hygiene --skill doc-freshness-reverse-lint-wan-huiyan
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: doc-freshness-reverse-lint
Source: https://github.com/wan-huiyan/claude-ecosystem-hygiene/tree/main/plugins/doc-freshness-reverse-lint
Command: npx skills add https://github.com/wan-huiyan/claude-ecosystem-hygiene --skill doc-freshness-reverse-lint-wan-huiyan

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? When you record a correction like "don't sort by p-value" in your Claude memory files (lessons.md, axioms.md, or feedback_*.md), the project docs that originally recommended that practice stay stale, and future sessions keep repeating the retracted advice. This skill catches those contradictions automatically. ## Core Features & Use Cases - Event-driven reverse-lint: A PostToolUse hook fires when a memory file is edited, extracts the new negation rule, greps project docs, and surfaces file:line candidate stale claims — never auto-edits. - Dead-branch detection: Finds retired rules whose scoped conditions ("still applies if you are a Y") survive in docs after the condition no longer exists. - Weekly cron audit: A safety-net scan of docs/{research,decisions,findings,runbooks}/ against recent negation rules, including near-duplicate detection at 70% token overlap. - Use Case: You add a lesson "never deploy on Fridays" — the hook immediately flags that docs/runbooks/release.md still recommends Friday deploys, so you can update it before the next session reads it as authoritative. ## Quick Start Ask the assistant to run the doc freshness audit against your project to check whether any docs still contradict your recent lessons and feedback entries.

Frequently Asked Questions about doc-freshness-reverse-lint

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect stale documentation after updating Claude memory files?

Run reverse_lint.py against the edited memory file with a project root, or wire the bundled hook_dispatch.sh as a PostToolUse hook on Edit|Write. It extracts new negation rules and greps project docs for literal matches, returning file:line candidates.

How do I wire the PostToolUse hook for doc freshness checks?

Resolve the absolute path of hook_dispatch.sh using the three-root lookup (CLAUDE_PLUGIN_ROOT, ~/.claude/skills, or the plugin cache), then paste that literal path into settings.json under hooks.PostToolUse for the Edit|Write matcher. Re-resolve after every plugin upgrade because the cache path contains the version segment.

Does the doc freshness lint automatically edit my documentation files?

No, it never modifies any file. It only outputs candidate stale claims as file:line references, and every candidate requires human judgment to decide whether the guidance is actually stale.

Why does the reverse-lint hook stay silent after I edit lessons.md?

Silence is expected when there are zero matches, by design. It also stays silent if the rule lacks an explicit negation trigger, the extracted phrase has fewer than two tokens, or the rule was already processed and stored in the seen-cache at ~/.claude/state/reverse-lint-seen.json.

What is dead-branch detection in documentation audits?

Dead-branch detection finds retired rules whose scoped conditions still read as live guidance, such as "X is retired but still applies if you are a Y" after no Y exists. It requires three ANDed signals: a retirement trigger, a quoted subject, and a surviving conditional in the same doc paragraph.

What are the limitations of literal-phrase documentation linting?

It performs only literal and stem-normalized grep, so rephrased or qualified contradictions are not caught by the event-driven lint. The weekly audit adds near-duplicate detection at 70% token overlap, but semantic interpretation still requires human review.