Quality validation - auto-fix linting, check links, consistency, completeness
/plugin marketplace add kimcharli/ck-skills/plugin install doc-review-commands@ck-skillsfind . -name "*.md" | wc -lgit log -5 --oneline -- "*.md" 2>/dev/null || echo "No recent doc commits"Quality validation and auto-fix - Automatically fixes formatting issues with linting tools, then performs validation checks for links, consistency, and completeness.
# Check if markdownlint is available
which markdownlint || npm list -g markdownlint || echo "markdownlint not found"
# Check if prettier is available
which prettier || npm list -g prettier || echo "prettier not found"
If tools are not available:
npm install -g markdownlint-cli prettier
Run markdownlint with auto-fix enabled:
markdownlint --fix . --ignore node_modules --ignore '.git'
This automatically fixes:
Run prettier for consistent formatting:
prettier --write "**/*.md"
This formats:
# Show what was changed
git diff --name-only 2>/dev/null || echo "Not a git repo"
# Count auto-fixed issues
echo "✅ Auto-fix complete"
Search for markdown links in all .md files:
# Find all links
find . -name "*.md" -exec grep -o '\[.*\](.*\.md)' {} +
# Find relative links
find . -name "*.md" -exec grep -o '](\.\.*/.*\.md)' {} +
For each link found:
Report Format:
✅ Valid links: [count]
❌ Broken links: [count]
⚠️ External links: [count] (manual review needed)
Broken Links Found:
- file.md:123 → links to missing-file.md
- [...]
Find all code references (e.g., path/to/file.py:123):
find . -name "*.md" -exec grep -o '[a-zA-Z0-9_/.-]*\.[a-z]*:[0-9]*' {} +
For each reference:
Report Format:
✅ Valid references: [count]
❌ Invalid file references: [count]
⚠️ Questionable line numbers: [count]
Issues Found:
- README.md mentions deleted_file.py:50
- CLAUDE.md references file.py:999 (file only has 200 lines)
Find variations of important terms:
# Example: Find all variations of "apstra"
grep -i "apstra\|APSTRA\|Apstra" . -r --include="*.md"
# Check for inconsistent capitalization
# Check for inconsistent naming (e.g., "doc review" vs "doc-review")
Report Format:
📝 Terminology Review:
Consistent:
- ✅ "Apstra" used consistently (capitalized)
- ✅ "NetworkX" spelling consistent
Inconsistent:
- ⚠️ "doc-review" vs "doc review" (3 vs 2 occurrences)
- ⚠️ "Python" vs "python" mixed usage
Recommendations:
- Standardize on "doc-review" (hyphenated)
- Use "Python" (capitalized) for language name
# Find version patterns
grep -E "v?[0-9]+\.[0-9]+\.[0-9]+" . -r --include="*.md"
grep -E "version.*[0-9]" . -r --include="*.md" -i
Report Format:
📊 Version Consistency:
Found Versions:
- README.md: v1.2.0
- CHANGELOG.md: 1.2.0 (latest entry)
- pyproject.toml: 1.1.5
Issues:
- ❌ Version mismatch: README (1.2.0) vs pyproject.toml (1.1.5)
Recommendation:
- Update pyproject.toml to 1.2.0 or clarify version strategy
Find all requirement IDs (FR-*, NFR-*):
grep -E "(FR|NFR)-[0-9]+" . -r --include="*.md"
Report Format:
🔍 SDD Traceability:
Requirements in spec.md: [count]
Requirements in plan.md: [count]
Requirements in tasks.md: [count]
Orphaned Requirements:
- FR-005 appears in spec.md but not in tasks.md
- [...]
Completed but Not Marked:
- FR-003 marked done in tasks.md but not in spec.md
# Find all code fences
grep -E "^\`\`\`" . -r --include="*.md"
python vs)?Report Format:
💻 Code Example Review:
Code blocks found: [count]
Language specified: [count]/[total]
Unclosed fences: [count]
Issues:
- README.md:50 - Code fence not closed
- CLAUDE.md:120 - No language specified
Check if standard files have expected sections:
README.md:
CLAUDE.md:
CHANGELOG.md:
Report Format:
📋 Completeness Check:
README.md:
- ✅ Has installation section
- ✅ Has usage examples
- ❌ Missing troubleshooting section
CLAUDE.md:
- ✅ Has architecture overview
- ⚠️ Core modules section is sparse
Validation Date: [YYYY-MM-DD]
Linting & Formatting Phase:
Common fixes applied:
Baseline Score: [X]/100 (before fixes) After Fixes: [X]/100 (after linting)
High Priority (Fix Immediately):
Medium Priority (Fix Soon):
Low Priority (Nice to Have):
Fix broken links:
Update version numbers:
Standardize terminology:
Complete missing sections:
git commit -m "docs: Auto-fix linting issues (markdownlint + prettier)"/ck:doc-review/qaTools use standard configurations:
.markdownlintrc - Markdownlint rules (if present).prettierrc - Prettier rules (if present)