Documentation Drift Report¶

Repository: /Users/veronica.bolognesi/.agents/skills/zolletta-metaskill
Scan Date: 2026-08-06
Generated By: zolletta-metaskill documentor
Documentation directory: docs/ (from documentation.dir in settings.json)

Grade¶

Metric	Value
Overall Score	73/100

Justification: The documentation directory docs/ contains 53 markdown files across all four Diátaxis quadrants plus ADRs. The aggregate staleness score is 73.8/100 (good). Four broken links were found (3 file-not-found, 1 empty anchor), 7 duplicate anchors, 14 documented-but-not-in-source API mismatches, 3 missing parameter docs, and 22 drift issues (21 manual review, 1 semi-automated). Points were deducted for broken links, API mismatches, and drift in low-scoring files.

Category	Points Available	Points Earned	Notes
Diátaxis compliance	40	34	All 4 quadrants present; 1 tutorial only (thin), ADRs well-structured
Drift detection (staleness)	20	13	Aggregate score 73.8; 6 files scored critical/abandoned
Drift detection (broken links)	15	11	4 broken links, 7 duplicate anchors
Drift detection (API validation)	15	10	14 phantom symbols, 3 missing params
Structural gaps / consistency	10	5	README missing Installation/License/Usage sections
Total	100	73

Summary¶

Metric	Value
Documentation files scanned	53
Files with drift detected	22
Overall staleness score	73.8/100 (good)
Broken links found	4
Duplicate anchors	7
API mismatches found	17 (14 phantom + 3 missing params)

Diátaxis Compliance¶

Quadrant	Count	Status
Tutorials	1	Thin — only `install.md`
How-to guides	11	Good coverage
Reference	15	Good coverage
Explanation	14	Good coverage
ADRs	11	Well-structured

Issues: - Tutorials quadrant has only 1 file — consider adding onboarding tutorials for new users.

Staleness Scores¶

Aggregate score: 73.8/100 (good) — 75 documents scored (includes SKILL.md files).

Critical / Abandoned files (score < 50)¶

File	Score	Label
`skills/review/assets/summary_template.md`	29.1	abandoned
`skills/review/assets/todo_template.md`	29.1	abandoned
`docs/adr/adr-distilled.md`	31.2	critical
`skills/external-review/SKILL.md`	42.9	critical
`skills/python-code-style/SKILL.md`	45.2	critical
`docs/adr/0009-inline-shell-replaced-with-python-scripts.md`	46.2	critical
`skills/patterns/SKILL.md`	48.2	critical
`skills/review/SKILL.md`	48.5	critical
`skills/php-testing-style/SKILL.md`	48.6	critical
`skills/python-testing-style/SKILL.md`	50.0	critical

Note: SKILL.md files score low on code-doc alignment because they reference scripts that were recently renamed. The adr-distilled.md is auto-generated and scores low because it has no inbound links or code references.

Drift Issues¶

Critical Severity¶

File	Issue	Category	Fix Type
`README.md`	Missing recommended section: Installation	structural	Manual
`README.md`	Missing recommended section: License	structural	Manual
`README.md`	Missing recommended section: Usage	structural	Manual

High Severity¶

File	Issue	Category	Fix Type
`docs/reference/code/scripts.md`	366 code files changed since doc last updated	factual	Manual
`docs/explanation/code/python/python-review-patterns.md`	366 code files changed since doc last updated	factual	Manual
`docs/explanation/code/php/php-review-patterns.md`	366 code files changed since doc last updated	factual	Manual
`docs/explanation/code/false-positive-prevention.md`	366 code files changed since doc last updated	factual	Manual
`docs/explanation/code/general-principles.md`	366 code files changed since doc last updated	factual	Manual
`docs/explanation/code/structural-conventions.md`	366 code files changed since doc last updated	factual	Manual
`docs/reference/documentation/operational-rules.md`	527 code files changed since doc last updated	factual	Manual
`docs/reference/documentation/drift-detection-tools.md`	527 code files changed since doc last updated	factual	Manual

Medium Severity¶

File	Issue	Category	Fix Type
`docs/reference/code/scripts.md`	14 documented symbols not found in source (renamed scripts)	factual	Semi-automated
`docs/reference/code/scripts.md`	3 missing parameter docs	factual	Manual
Multiple SKILL.md files	Code files changed since last update	factual	Manual

Low Severity¶

File	Issue	Category	Fix Type
`skills/review/assets/summary_template.md`	427 code files changed, no source references	factual	Manual
`skills/review/assets/todo_template.md`	427 code files changed, no source references	factual	Manual

Broken Links¶

File	Line	Link	Error
`explanation/code/false-positive-prevention.md`	77	`[#]`	Empty anchor `#` not found
`explanation/documentation/adr.md`	81	`[ADR-0003](adr/0003-adopt-microservices.md)`	File not found
`reference/reports.md`	42	`[report template](../../review/assets/summary_template.md)`	File not found
`reference/settings-schema.md`	13	`[setup/assets/settings.schema.json](../../setup/assets/settings.schema.json)`	File not found

Duplicate Anchors (7)¶

File	Anchor
`explanation/code/structural-conventions.md`	`#good` (line 167)
`reference/code/scripts.md`	`#dependency_inversion_scannerpy-dip` (line 194)
`reference/code/scripts.md`	`#interface_segregation_scannerpy-isp` (line 212)
`reference/code/scripts.md`	`#open_closed_scannerpy-ocp` (line 229)
`reference/documentation/workflows-and-tools.md`	`#json-output` (line 134)
`reference/tool-messages.md`	`#tool-unconfigured-warnings` (line 15)

API Doc Validation¶

Documented but not in source (14 phantom symbols)¶

Symbol	Likely Cause
`test_file_pattern`	Renamed to `test_glob_pattern_returns_glob`
`get_engine_for_file`	Renamed to `get_for_file`
`get_engine`	Renamed to `get`
`register_engine`	Renamed to `register`
`make_container`	Example/illustrative, not real code
`Container`	Example/illustrative, not real code
`ensure_engine`	Example/illustrative, not real code
`validate`	Example/illustrative, not real code
`declare`	Example/illustrative, not real code
`reset`	Removed or renamed
`set`	Removed or renamed
`output_dir.mkdir`	Example/illustrative
`sys.exit`	Example/illustrative
`self._initialize`	Example/illustrative

Missing parameters in docs (3)¶

Parameter	Source	Doc
`path`	`php_engine.py:186` (`parse_raw`)	`docs/adr/0007-language-neutral-engine-protocol.md`
`language`	`engine_registry.py:41` (`get`)	`docs/explanation/code/python/python-review-patterns.md`
`path`	`php_engine.py:186` (`parse_raw`)	`docs/reference/code/scripts.md`

Auto-Fixable Issues¶

Duplicate anchors in scripts.md: 3 anchors reference old script names (dependency_inversion_scannerpy-dip, etc.) — can be auto-fixed by updating to new names.

Manual Review Required¶

README.md — add missing Installation, License, and Usage sections.
Broken link in adr.md — adr/0003-adopt-microservices.md does not exist; update link to the correct ADR.
Broken link in reports.md — ../../review/assets/summary_template.md path is wrong; fix to correct relative path.
Broken link in settings-schema.md — ../../setup/assets/settings.schema.json path is wrong; fix to correct relative path.
Empty anchor in false-positive-prevention.md — line 77 has [#] which is an empty anchor; fix the link target.
14 phantom API symbols — update docs/reference/code/scripts.md and related docs to use the new method names (get, register, get_for_file, test_glob_pattern_returns_glob).
3 missing parameter docs — add path and language parameters to the relevant docs.

Recommendations¶

Fix 4 broken links — all are path or anchor issues that can be resolved quickly.
Update scripts.md — 14 phantom symbols are from the recent scanner/method renames; update the doc to match the new names.
Add README sections — Installation, License, and Usage are expected sections that are missing.
Add tutorials — the tutorials quadrant has only 1 file; consider adding onboarding guides.
Fix duplicate anchors — 7 duplicate anchors in 5 files; rename headings or use explicit anchor syntax.

Score Breakdown¶

Dimension	Weight	Score	Weighted
Last Updated	20%	73.8	14.8
Code-Doc Alignment	30%	~60	18.0
Link Health	15%	98.4	14.8
Completeness	20%	~70	14.0
Accuracy	15%	~75	11.2
Total	100%		73/100

Generated by zolletta-metaskill documentor