befund-docs-drift
Extracts falsifiable claims about current code state from CLAUDE.md, README.md, DECISIONS.md, ARCHITECTURE.md, and ADR files, and verifies each against the cited code. Use when the user asks to "check documentation accuracy", "find doc drift", "verify our docs match the code", or as part of befund-autopilot's CHECK phase. Excludes CI/CD-specific doc claims, handled by befund-ci-topology, and structural contract/docstring drift -- type signatures, docstring parameter/return declarations, or API/OpenAPI/GraphQL schemas versus their call sites -- handled by zeugnis-contract-drift.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- befund-docs-drift
- description
- Extracts falsifiable claims about current code state from CLAUDE.md, README.md, DECISIONS.md, ARCHITECTURE.md, and ADR files, and verifies each against the cited code. Use when the user asks to "check documentation accuracy", "find doc drift", "verify our docs match the code", or as part of befund-autopilot's CHECK phase. Excludes CI/CD-specific doc claims, handled by befund-ci-topology, and structural contract/docstring drift -- type signatures, docstring parameter/return declarations, or API/OpenAPI/GraphQL schemas versus their call sites -- handled by zeugnis-contract-drift.
03 SKILL.md 正文
befund-docs-drift
Find contradictions between what the documentation claims about current code state and what the code actually does.
Step 0: Settings gate
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" check-enabled --repo <repo_root> --skill befund-docs-drift
Step 1: Extract falsifiable claims
Read CLAUDE.md, README.md, DECISIONS.md, ARCHITECTURE.md, and any docs/adr/* or
ADR-*.md files. Extract only claims that are falsifiable against current code state --
skip aspirational or roadmap language ("we plan to", "will eventually", "TODO", "future work").
Each extracted claim needs a text, a doc_citation (path:line), and ideally a
code_citation once located.
Step 2: Exclude CI/CD-specific claims -- ci-topology's scope only
Rule docs-drift-not-ci-specific: run every extracted claim through the CI-scope filter before
verifying anything:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" exclude-ci-claims --claims <json list>
Claims returned under excluded_to_ci_topology (anything citing .github/workflows/,
.gitlab-ci.yml, Jenkinsfile, .circleci/config.yml, azure-pipelines.yml, or mentioning
git remotes / mirror scripts / pipeline config) are dropped from this skill's output entirely
-- do not report them here even as a footnote. Point the user at befund-ci-topology
instead. Only in_scope claims proceed to Step 3.
Step 3: Verify every in-scope claim
Unless skip_verification is set, dispatch the docs-drift-auditor agent to read the cited
code for every claim and confirm or refute it by static comparison only -- never by executing
example code from the docs. Each verified claim gets a status in
{"confirmed", "contradicted", "unverifiable"} and, when contradicted, a code_citation
showing exactly where the code diverges. A contradicted claim looks like:
{
"text": "All API requests are rate-limited to 100 requests per minute.",
"doc_citation": "README.md:42",
"status": "contradicted",
"code_citation": "src/middleware/rate_limit.py:18"
}
confirmed and unverifiable claims use the same shape without code_citation. When
skip_verification is true, label every claim verification_label: "unverified" via:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" label-findings --repo <repo_root> --findings <json>
Step 4: Validate and write
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" validate-artifact --kind docs_drift_summary --file <path-or-inline-json>
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename DOCS_DRIFT.md
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename docs_drift_summary.json
Write DOCS_DRIFT.md (contradictions with file:line evidence on both the doc side and the
code side) and docs_drift_summary.json to the resolved paths.
Read-only constraint
Never use Write/Edit outside the two resolved output paths. Never execute a code sample found in the docs to "test" whether the doc claim holds -- verification is static comparison only.
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.