Skip to main content

/lint-docs - Documentation Quality Command

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Description​

Run comprehensive documentation linting and quality validation on markdown files. Executes markdownlint-cli2, yamllint, link checking, and generates quality reports.

Usage​

/lint-docs                    # Lint all markdown files
/lint-docs --fix              # Lint and auto-fix issues
/lint-docs --file FILE        # Lint specific file
/lint-docs --report           # Generate full quality report

What This Does​

  1. Markdown Linting: Runs markdownlint-cli2 on all .md files
  2. YAML Validation: Validates frontmatter in documentation files
  3. Link Checking: Detects broken internal and external links
  4. Quality Scoring: Generates comprehensive quality reports
  5. Auto-Fix: Automatically fixes common issues (if --fix flag used)

Options​

  • --fix: Auto-fix linting issues where possible
  • --file FILE: Lint specific file instead of all files
  • --report: Generate detailed quality report in docs/DOCUMENTATION-QUALITY-REPORT.md
  • --strict: Fail on warnings (not just errors)

Examples​

Example 1: Lint All Documentation​

/lint-docs

Output:

Running documentation quality checks...

✅ Markdown linting: 127 files checked, 0 errors
✅ YAML frontmatter: 127 files validated, 3 warnings
⚠️  Link checking: 2 broken internal links found
✅ Quality score: 93.2/100 (Grade A)

Warnings:
- docs/guides/old-guide.md: Missing 'author' field
- docs/api/endpoints.md: Missing 'author' field
- README.md: Missing 'author' field

Issues:
- docs/deployment/kubernetes.md: Broken link to deleted file
- docs/api/authentication.md: Broken link to moved file

Run '/lint-docs --fix' to auto-fix issues.
See docs/DOCUMENTATION-QUALITY-REPORT.md for details.

Example 2: Auto-Fix Issues​

/lint-docs --fix

Output:

Running documentation quality checks with auto-fix...

Fixing markdown issues...
- Fixed 12 line length violations
- Fixed 3 list marker inconsistencies
- Fixed 8 code block language specifications

✅ All auto-fixable issues resolved
⚠️  2 broken links require manual intervention

Manual fixes needed:
1. docs/deployment/kubernetes.md:45 - Update link to docs/deployment/k8s-setup.md
2. docs/api/authentication.md:12 - Update link to docs/auth/oauth.md

Quality score improved: 93.2 → 96.8 (+3.6)

Example 3: Lint Specific File​

/lint-docs --file docs/guides/quick-start.md

Output:

Linting docs/guides/quick-start.md...

✅ Markdown: No issues
✅ YAML frontmatter: Valid
✅ Links: All functional
✅ Quality score: 98/100 (Grade A)

Recommendations:
- Add troubleshooting section (+2 points potential)

Example 4: Generate Full Quality Report​

/lint-docs --report

Output:

Generating comprehensive documentation quality report...

Files audited: 127
Total issues: 14
Average score: 93.2/100 (Grade A)

Report generated: docs/DOCUMENTATION-QUALITY-REPORT.md

Top recommendations:
1. Fix 2 broken links (10 min)
2. Add missing frontmatter fields (5 min)
3. Update 3 outdated guides (45 min)

Estimated remediation time: 60 minutes

Implementation​

This command executes:

#!/bin/bash
# Invoked by /lint-docs

./scripts/lint-all.sh "$@"

# If --report flag, generate quality report
if [[ "$*" == *"--report"* ]]; then
  python3 scripts/generate-doc-quality-report.py
fi
  • /fix-docs - Auto-fix all documentation issues
  • /check-links - Run only link checker
  • Agent: documentation-quality-agent - Full quality assessment
  • Script: ./scripts/lint-all.sh - Direct script execution

Exit Codes​

  • 0: All checks passed
  • 1: Linting errors found
  • 2: Broken links found
  • 3: Quality score below threshold (<95)

Action Policy​

<default_behavior> This command executes linting and reports. Provides:

  • Markdown lint results
  • YAML frontmatter validation
  • Link checking
  • Quality score

Auto-fixes when --fix flag used. </default_behavior>

After linting, provide: - Files checked count - Error/warning counts - Quality score - Broken links (if any)

Success Output​

When lint-docs completes:

✅ COMMAND COMPLETE: /lint-docs
Files: N checked
Errors: N
Warnings: N
Quality: N/100 (Grade X)

Completion Checklist​

Before marking complete:

  • Markdown linting run
  • YAML validated
  • Links checked
  • Score calculated

Failure Indicators​

This command has FAILED if:

  • ❌ No files found
  • ❌ Linter not installed
  • ❌ Exit code non-zero

When NOT to Use​

Do NOT use when:

  • Non-markdown files
  • Binary files
  • Generated documentation

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Skip --fixManual fixesUse --fix for auto-fix
Ignore warningsQuality debtAddress all warnings
Skip link checkBroken linksAlways check links

Principles​

This command embodies:

  • #3 Complete Execution - Full lint workflow
  • #6 Clear, Understandable - Clear quality score
  • #9 Based on Facts - Evidence-based quality

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Last Updated: 2025-12-06 Version: 1.0.0 Command: /lint-docs