artsmc Document Hub: Analyze
Analyze documentation quality and detect drift from the actual codebase. This is a read-only diagnostic: report problems and recommendations, make no changes. Suggest /document-hub update if drift is detected.
Helper Scripts — canonical copies live in /home/artsmc/.claude/skills/document-hub-initialize/scripts/ (see its README.md for full docs):
detect_drift.py <project>- module + technology drift (JSON: drift scores + specific gaps)extract_glossary.py <project>- ranked undocumented domain terms with contextsvalidate_hub.py <project>- structure validation (JSON: structural issues)
Analysis Workflow
Run all six phases, then present findings without making changes.
Phase 1: Validation Check
python /home/artsmc/.claude/skills/document-hub-initialize/scripts/validate_hub.py /path/to/project
If validation fails: report structural errors, recommend fixing before analyzing content, and exit early if the hub doesn't exist.
Phase 2: Module Drift
python /home/artsmc/.claude/skills/document-hub-initialize/scripts/detect_drift.py /path/to/project
Returns:
{
"drift_score": 0.23,
"module_drift": {
"undocumented": ["analytics", "webhooks"],
"documented_but_missing": ["legacy"]
}
}
undocumented→ code exists (src/) but not in keyPairResponsibility.mddocumented_but_missing→ docs reference non-existent code
Phase 3: Technology Drift
Same detect_drift.py output:
{
"technology_drift": {
"undocumented": ["Redis", "BullMQ"],
"documented_but_missing": ["MongoDB"]
}
}
Check package.json/requirements.txt vs techStack.md; identify when tech was added (git log) and whether it is actually in use.
Phase 4: Glossary Gaps
python /home/artsmc/.claude/skills/document-hub-initialize/scripts/extract_glossary.py /path/to/project
Returns ranked terms from the codebase. Read the existing cline-docs/glossary.md, identify terms in code but not in the glossary, rank by the script's importance score, and recommend the top 10-20 additions.
Phase 5: Health Scoring
Health Score = 100 - (drift_score * 100)
| Score | Drift | Rating | Action |
|---|---|---|---|
| 90-100 | < 0.10 | Excellent - minor gaps only | continue monitoring |
| 75-89 | 0.10-0.25 | Good - easy to fix | update as needed |
| 60-74 | 0.25-0.40 | Needs Attention - significant gaps | schedule update next sprint |
| < 60 | > 0.40 | Poor - major documentation debt | run /document-hub update now |
Regardless of score, immediate action is needed for drift > 0.35, multiple undocumented core modules, or broken cross-references.
Phase 6: Recommendations
Prioritize by impact:
- HIGH: undocumented modules with many files; missing critical technologies (databases, frameworks); broken cross-references
- MEDIUM: documented-but-missing code; complex diagrams needing split; missing glossary terms for core concepts
- LOW: minor tech stack updates; formatting inconsistencies; additional glossary terms
Report Format
The full report template (section structure with sample output) and a complete Python example that runs all three scripts and assembles the report live in references/report-format.md — read it before presenting findings.
Use Cases
- Pre-update health check - run before
/document-hub updateto understand scope and prioritize changes - Periodic audit (monthly/quarterly) - track health score trend, address high-priority items
- Onboarding validation - when taking over a project, gauge documentation completeness and identify knowledge gaps
Best Practices & Pitfalls
- ✅ Run before updating; use findings to guide updates; track health score trends over time
- ✅ Prioritize high-impact recommendations - don't try to fix everything at once
- ❌ Don't make changes during analysis - this is read-only
- ❌ Don't ignore high-priority items - they indicate real gaps
- ❌ Don't run too frequently - analysis is for planning, not continuous monitoring