doc-drift

name	doc-drift
description	Check whether recent commits have made the root CLAUDE.md, docs/README.md, or key docs stale — new packages not listed, changed build commands, dependency version drift, new brand variants, or product changes that invalidate documented strategy. Run deliberately after a batch of work or before a release, not on every session.

Doc Drift

Why this is a skill and not a session hook

This ran as a SessionStart hook, spending two git calls plus reasoning on every session — including the many that never touch a documented surface. Documentation drift accrues over weeks, not over single sessions, so paying that cost per-session bought very little. It is now invoked when it is actually likely to find something: after a batch of work, before a release, or when a package or dependency has moved.

Outcome

• A short list of specific doc sections that no longer match the code, each with the evidence that contradicts them
• With fix: those sections updated
• Silence when nothing has drifted — do not manufacture findings

Steps

1. Establish what changed

git log --oneline -30 --no-merges
git diff --name-only HEAD~30 HEAD

Use --since <ref> if the user supplies one (e.g. --since origin/stage). Prefer the last release tag or the last merge to stage over a fixed commit count when one exists.

2. Check each claim that is cheap to falsify

Only these — this is a drift check, not a documentation review.

Claim in docs	How to falsify it
Package list in CLAUDE.md "Monorepo Structure"	ls -d */ therr-services/*/ therr-public-library/*/
Node / npm versions	cat .nvmrc, engines in root package.json
React / RN / TypeScript versions	package.json and TherrMobile/package.json
Build/lint/test commands	scripts in root package.json — do the documented ones still exist?
BrandVariations enum members	therr-public-library/therr-js-utilities/src/constants/enums/Branding.ts
Locale list (en-us, es, fr-ca)	scripts/locale-check/package-targets.json
Ports in "Monorepo Structure"	docker-compose.dev.yml
Every docs/*.md is linked from docs/README.md	compare ls docs/*.md against links in the index
Skills referenced by CLAUDE.md exist	ls .claude/skills/
CI job names cited in docs	.circleci/config.yml

3. Check strategy docs only if the product moved

If commits touched pricing, onboarding, the claim funnel, or a brand's status, re-read docs/GROWTH_STRATEGY.md, docs/TARGET_MARKETS.md, and the relevant docs/niche-sub-apps/*_PROJECT_BRIEF.md for assumptions the change invalidates.

Skip this entirely for routine code changes.

4. Report

For each finding, give the doc, the line or section, the claim, and the contradicting evidence. Keep it to the 1–3 that matter. Example:

CLAUDE.md "Key Dependencies" says React Native 0.83.6, but TherrMobile/package.json now pins 0.84.1 (commit abc1234).

If invoked as fix, apply the edits. Otherwise stop at the report.

5. Say nothing when nothing drifted

A clean result is one line: "No drift found across N commits." Do not pad it.

Guardrails

• Do not rewrite prose you merely dislike. Only factual contradictions count.
• Do not grow CLAUDE.md. It is deliberately ~250 lines; long always-on context measurably degrades agent performance. If a section needs more detail, move it to a doc or a skill and leave a pointer.
• Corrections to package-level CLAUDE.md files must respect branch rules — those under therr-services/, therr-api-gateway/, and therr-public-library/ belong on general.