From harness-claude
Detects documentation drift from code using harness check-docs, cleanup, git diff, and graph queries. Run after features, refactoring, code reviews, or periodically.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> Detect documentation that has drifted from code. Find stale docs before they mislead developers and AI agents.
Detects documentation drift, stale references, and cross-document inconsistencies in projects. Scans code-doc mismatches, broken links, outdated versions, and git staleness.
Verifies documentation references (file paths, CLI commands, config keys, env vars) against codebase and proposes updates for git diff-affected docs.
Syncs AGENTS.md, API docs, and architecture docs with code changes via git diff after features, bug fixes, or refactors.
Share bugs, ideas, or general feedback.
Detect documentation that has drifted from code. Find stale docs before they mislead developers and AI agents.
on_post_feature or on_doc_check triggers fireRun harness check-docs to identify all documentation issues. Capture the full output.
Run harness cleanup --type drift for a deeper analysis that cross-references code changes against documentation references.
Check for stale constraints. Run detect_stale_constraints alongside drift detection to find architectural constraints that no longer match the codebase.
Optionally, run git diff against a baseline (last release, last sprint, etc.) to identify which code files changed. This helps prioritize — docs for recently changed files are most likely to be drifted.
When a knowledge graph exists at .harness/graph/, use graph queries for faster, more accurate drift detection:
query_graph — find documents edges where the target code node has changed since the doc node was last updatedWhen a graph is available, drift is simply stale edges: doc-to-code edges where the code side has been modified more recently than the doc side. This replaces regex pattern matching and catches semantic drift that text search misses. Fall back to file-based commands if no graph is available.
When invoked by harness-docs-pipeline, check for a pipeline field in .harness/handoff.json:
pipeline field exists: read DocPipelineContext from it
pipeline.exclusions to skip findings that were already addressed in a previous phaseDriftFinding[] results back to pipeline.driftFindings in handoff.jsonpipeline field does not exist: behave exactly as today (standalone mode)No changes to the skill's interface or output format — the pipeline field is purely additive.
Categorize each finding into one of these drift types:
Renamed but not updated: A function, class, variable, or file was renamed in code, but documentation still references the old name. This is the most common type of drift.
calculateShipping() was renamed to computeShippingCost(), but AGENTS.md and three inline comments still say calculateShipping.New code with no docs: A new module, function, or API was added but no documentation entry exists. This is not "drift" in the strict sense but a gap that grows into drift over time.
src/services/notification-service.ts was added two sprints ago. It has 5 public exports. No AGENTS.md section, no doc page, no inline doc comments beyond basic JSDoc.Deleted code still referenced: A file, function, or feature was removed, but documentation still describes it as if it exists. This actively misleads readers.
src/utils/legacy-parser.ts was deleted. The architecture doc still includes it in the data flow diagram. AGENTS.md still warns about its quirks.Changed behavior not reflected: A function's signature, return type, error handling, or side effects changed, but the documentation describes the old behavior.
createUser() now throws ValidationError instead of returning null on invalid input. The API docs still say "returns null if validation fails."Moved code with stale paths: A file or module was moved to a different directory, but documentation references the old path.
src/helpers/format.ts was moved to src/utils/format.ts. Three doc files and AGENTS.md reference the old path.Not all drift is equally harmful. Prioritize fixes:
Critical (fix immediately):
High (fix before next release):
Medium (fix in next sprint):
Low (fix when convenient):
For each drift finding, provide:
Group findings by documentation file so that fixes can be applied file-by-file.
harness check-docs — Primary tool. Scans all documentation files for broken references, stale paths, and missing entries.harness cleanup --type drift — Deeper analysis that cross-references git history with documentation references to detect semantic drift.harness cleanup --type drift --json — Machine-readable output for automated pipelines.harness fix-drift — Auto-fix simple drift issues after review (use align-documentation skill for applying fixes).harness check-docs reports zero errors| Rationalization | Why It Is Wrong |
|---|---|
| "The docs are close enough -- a renamed function is obvious from context" | Renamed references in AGENTS.md cause AI agents to hallucinate about non-existent code. Precision matters. |
| "We only changed internal code, so the docs do not need checking" | Internal API docs with wrong signatures waste developer debugging time. Changed-behavior-not-reflected drift is High priority. |
| "There are too many findings to deal with right now, so skip the scan" | The escalation protocol exists for this case: focus on Critical and High items, create a tracking issue for the rest. |
| "We can rely on code review to catch stale docs" | Code reviewers focus on code correctness, not documentation cross-references. harness check-docs catches what humans routinely miss. |
Drift finding:
DRIFT: Renamed reference detected
Doc: AGENTS.md:47
Stale text: "Use `calculateShipping()` to compute shipping costs"
Code change: calculateShipping renamed to computeShippingCost (commit a1b2c3d)
File: src/services/shipping.ts:24
Priority: High
Suggested fix: Replace `calculateShipping()` with `computeShippingCost()`
Drift finding:
DRIFT: Reference to deleted file
Doc: docs/architecture.md:112
Stale text: "The legacy parser (src/utils/legacy-parser.ts) handles XML input"
Code change: File deleted in commit d4e5f6g, functionality merged into unified-parser.ts
Priority: Critical
Suggested fix: Update section to reference unified-parser.ts, remove legacy parser description
Drift finding:
GAP: Undocumented module
File: src/services/notification-service.ts
Created: commit h7i8j9k (3 weeks ago)
Public exports: NotificationService, NotificationType, sendNotification
Imported by: 4 modules
Documentation references: 0
Priority: High
Suggested fix: Add AGENTS.md section describing purpose, constraints, and public API
harness check-docs to the CI pipeline or pre-merge hooks to catch drift at the source.