| name | drift-check |
| description | Audit pg_turbovec docs/ against actual implementation. Flags stale test counts, version numbers, file structure, feature flags, and benchmark numbers that no longer match the code. |
pg_turbovec docs-drift check
This project ships a docs-heavy repo (docs/ARCHITECTURE.md, docs/INDEXAM.md,
docs/PARITY_GAPS.md, docs/RECALL.md, docs/PG_VERSION_SUPPORT.md,
, plus README + CHANGELOG). They drift fast.
This skill is the routine to keep them honest.
When to run
- After tagging a release.
- Before tagging a release.
- After landing any change that touches: pgrx version, the test count, a
PG version's support status, a benchmark number, a public type, or
the file layout under
src/.
- Periodically (every ~5 commits).
Workflow
For each item in the checklist below, compare the documented value to
the actual value. If they disagree, edit the doc and surface the diff
in your reply (don't silently fix without telling the user — they
might want to fix the code instead).
1. Version numbers
grep -E "^version" Cargo.toml
grep -E "default_version" pg_turbovec.control
grep -E "^## \[" CHANGELOG.md | head
git tag --list 'v*' --sort=-creatordate | head -3
Expected: Cargo.toml == pg_turbovec.control == top of CHANGELOG.md
(once "Unreleased" stanza is removed) == latest tag.
Note: --sort=-v:refname puts pre-release tags (v1.0.0-rc.1)
ahead of their final v1.0.0 because of how Git's version-sort
handles SemVer pre-release suffixes. Use --sort=-creatordate for
chronological order.
2. Test count
ANN=$(grep -rE '#\[(test|pg_test|pgrx::pg_test)\]' src/ | wc -l)
echo "actual annotations: $ANN"
grep -ohE "\b[0-9]+/[0-9]+\s*(passing|tests|test result|cases)" \
docs/*.md README.md CHANGELOG.md 2>/dev/null \
| sort | uniq -c | sort -rn | head
The annotation count is an upper bound; the test runner prints the
actual passed/failed count after --features pg<N> experimental_index_am pg_test. Documented numbers should match the runner output, not the
annotation count.
3. PG version support
grep -E '^pg[0-9]+ = ' Cargo.toml
cat docs/PG_VERSION_SUPPORT.md | grep -E '^\| [0-9]+'
ls ~/.pgrx
Cargo.toml's feature list must match docs/PG_VERSION_SUPPORT.md's
table. The .forgejo/workflows/test.yml matrix must also match.
4. File layout vs ARCHITECTURE.md
ls src/
ls src/index/
grep -E '^- `src/' docs/ARCHITECTURE.md | head -40
Every *.rs file under src/ should have a description in
docs/ARCHITECTURE.md. Any file mentioned in ARCHITECTURE.md that
doesn't exist anymore should be removed.
5. Feature flags
grep -A 20 "^\[features\]" Cargo.toml
grep -rE 'feature = "[^"]+"' README.md docs/USAGE.md docs/BUILDING.md
Documented build incantations like cargo build --features pg17 or
--no-default-features --features "pg17 experimental_index_am" must
work as written. Run a few to verify.
6. Benchmark numbers (the most fragile section)
docs/RECALL.md has the canonical numbers. Cross-check:
- README "headline" table (typically near the top) against
docs/RECALL.md section headers.
benches/results/*.json files referenced in RECALL.md must exist
and contain the cited numbers.- "post-fix" / "after commit X" claims should reference a real
short-SHA reachable from
main.
ls benches/results/
grep -E "(commit|p50|R@10|warm|cold).*[0-9]" docs/RECALL.md README.md \
| head -20
7. Roadmap claims
cat | grep -E '^### [12]\. |^- \*\*' | head
git log --oneline -20
If a "future work" item from has actually
landed (look for matching commit messages), move it from the future
section to the "What we shipped" section.
8. CHANGELOG vs git log
git log --oneline --since="$(git log -1 --format=%ai $(git tag --sort=-v:refname | head -2 | tail -1))" | head -20
grep -A 200 '^## \[' CHANGELOG.md | head -100
Every commit since the previous tag should be reflected in the
CHANGELOG entry for the current/next version. Bench, docs, and
chore commits can be summarised in one line; user-visible behaviour
or fixes need their own bullet.
9. Vendored dependencies
ls vendor/ 2>/dev/null
cat vendor/*/PATCH_NOTES.md 2>/dev/null | head -10
Anything in vendor/ should have a PATCH_NOTES.md describing
exactly what was changed vs upstream and the upstreaming status.
10. CI matrix
cat .forgejo/workflows/test.yml | grep -A 1 'matrix:'
cat .github/workflows/test.yml | grep -A 1 'matrix:' 2>/dev/null
grep -E '^pg[0-9]+ = ' Cargo.toml
Every PG version in Cargo.toml's features must appear in both
CI matrices.
Output format
After auditing, produce a single markdown report:
# pg_turbovec docs drift report — <YYYY-MM-DD>
## Drift found
- **<file>:<line> — <one-line description>**
Documented: `<old value>`
Actual: `<new value>`
Suggested fix: <action>
## Drift fixed
(any drift the agent fixed in-place, with the diff)
## All clear
(sections that audited clean)
## Suggestions
(non-drift improvements the audit surfaced)
Commit any in-place fixes with a docs(drift): prefix and reference
the commits / values that introduced the drift.
Anti-patterns
- Don't silently update benchmark numbers in docs without re-running
the bench. A "drift fix" that overwrites a bench number with
whatever the code currently does, without re-measuring, is fraud.
- Don't remove a doc section that describes deprecated behaviour
without checking whether real users still rely on it. The
docs/MIGRATING_FROM_PGVECTOR.md cookbook describes user-facing
behaviour and changing it is a breaking change.
- Don't drop a PG version from the docs without dropping it from
CI and
Cargo.toml too. That's the failure mode that gave us
v1.0.0 → v1.0.1.
