Initial commit

2025-11-30 08:40:02 +08:00
commit 0a8a6c982f
21 changed files with 4153 additions and 0 deletions
--- a/commands/docs/check.md
+++ b/commands/docs/check.md
@@ -0,0 +1,268 @@
+---
+description: "Validate documentation freshness, completeness, and quality"
+argument-hint: "[focus]"
+allowed-tools: ["Read", "Grep", "Glob", "Bash(git *, find *)"]
+---
+
+# Check Documentation Quality
+
+Validate documentation freshness, completeness, and quality against current codebase state.
+
+## Your Task
+
+1. **Parse Arguments**:
+   - Extract optional focus area from `$ARGUMENTS`
+   - Focus areas: `core`, `data`, `infrastructure`, `all`
+   - Default: check all documentation
+
+2. **Scan Documentation**:
+   - Find all documentation files in `docs/`
+   - Identify documentation types present
+   - Check for ADRs and RFCs
+
+3. **Analyze Project** (determine what docs should exist):
+   - Technology stack detection
+   - Database presence
+   - Deployment configurations
+   - Project type (library, app, service)
+
+4. **Perform Validation Checks**:
+
+   **A. Relevance Check**:
+   - Determine which docs are relevant to this project
+   - Identify missing documentation for detected technologies
+   - Example: If database models found, should have data-model.md
+
+   **B. Freshness Check**:
+   - Compare doc last-modified dates with related code changes
+   - Use git to check recent changes:
+   ```bash
+   # Check when files were last modified
+   !`git log -1 --format="%ai" -- docs/architecture.md 2>/dev/null`
+
+   # Check recent changes to codebase
+   !`git log --since="7 days ago" --oneline --name-only | head -50`
+   ```
+   - Flag docs that haven't been updated after significant code changes
+
+   **C. Completeness Check**:
+   - Verify all required sections are present
+   - Check for unreplaced placeholders: `{{PLACEHOLDER}}`
+   - Ensure diagrams exist where expected
+   - Verify ADRs have all sections (Status, Context, Decision)
+   - Verify RFCs have all sections (Summary, Motivation, Proposal)
+
+   **D. Quality Check**:
+   - Validate Mermaid diagram syntax
+   - Check for broken internal links (references to non-existent files)
+   - Verify markdown formatting
+   - Check for empty sections
+
+5. **Calculate Scores**:
+
+   **Freshness Scoring** (per document):
+   - Fresh (90-100): Updated within last 7 days or no related code changes
+   - Good (70-89): Minor code changes since last update
+   - Stale (50-69): Significant code changes since last update
+   - Outdated (<50): Major code changes or very old
+
+   **Completeness Scoring** (per document):
+   - Complete (90-100): All sections present, no placeholders
+   - Good (70-89): Most sections present, minor gaps
+   - Incomplete (50-69): Several missing sections
+   - Poor (<50): Major sections missing
+
+   **Quality Scoring** (per document):
+   - Excellent (90-100): No issues, all diagrams valid
+   - Good (70-89): Minor formatting issues
+   - Fair (50-69): Several issues
+   - Poor (<50): Major problems, broken diagrams
+
+   **Overall Score**:
+   - Average of all document scores
+   - Weight by importance (core docs > others)
+
+6. **Generate Report**:
+   - Status summary with overall score
+   - List of documents by status (Good, Needs Attention, Missing)
+   - Quality issues with specific locations
+   - Actionable recommendations
+
+## Validation Checks Detail
+
+### Missing Documentation
+```bash
+# Check for expected docs
+!`ls -1 docs/ 2>/dev/null | grep -E "architecture|onboarding|data-model|deployment"`
+
+# Check for ADRs
+!`ls -1 docs/adr/*.md 2>/dev/null | wc -l`
+
+# Check for RFCs
+!`ls -1 docs/rfc/*.md 2>/dev/null | wc -l`
+```
+
+### Stale Documentation
+```bash
+# Get last modification date of docs
+!`find docs -name "*.md" -exec stat -f "%Sm %N" -t "%Y-%m-%d" {} \; 2>/dev/null || find docs -name "*.md" -exec stat -c "%y %n" {} \;`
+
+# Get recent code changes
+!`git log --since="30 days ago" --name-only --pretty=format: | sort -u | grep -v "^$" | head -30`
+```
+
+### Placeholder Check
+```bash
+# Find unreplaced placeholders
+!`grep -r "{{.*}}" docs/ --include="*.md" 2>/dev/null`
+```
+
+### Broken Links
+```bash
+# Find markdown links
+!`grep -r "\[.*\](" docs/ --include="*.md" -h | grep -o "\[.*\](.*)" | head -20`
+```
+
+## Usage
+
+Check all documentation:
+```
+/docs:check
+```
+
+With specific focus:
+```
+/docs:check core
+/docs:check data
+/docs:check focus on database documentation
+```
+
+Quick check:
+```
+/docs:check quick
+```
+
+## Output Format
+
+### Status Summary
+```
+Documentation Health Report
+
+Overall Score: 85/100
+
+✅ Good (3 docs):
+  • docs/architecture.md (Score: 95/100)
+    - Last updated: 2 days ago
+    - All sections complete
+    - Diagrams valid
+
+  • docs/onboarding.md (Score: 92/100)
+    - Last updated: 1 week ago
+    - Comprehensive and current
+
+  • docs/adr/ (5 records, Score: 88/100)
+    - All ADRs properly formatted
+    - Recent decisions documented
+
+⚠️ Needs Attention (2 docs):
+  • docs/data-model.md (Score: 65/100)
+    - Outdated: Models changed 5 days ago (docs/data-model.md:1)
+    - Missing ER diagram
+    → Recommendation: Run /docs:diagram er
+
+  • docs/deployment.md (Score: 58/100)
+    - Missing deployment steps for new services
+    - Placeholder not replaced: {{DEPLOYMENT_STEPS}} (line 42)
+    → Recommendation: Run /docs:update deployment
+
+❌ Missing (2 docs):
+  • docs/security.md
+    - Security middleware detected but not documented
+    → Recommendation: Run /docs:init or /docs:diagram security
+
+  • docs/api-documentation.md
+    - 15 API endpoints found but not documented
+    → Recommendation: Run /docs:init
+
+🔧 Quality Issues:
+  • docs/data-model.md:42 - Invalid Mermaid syntax
+  • docs/architecture.md:15 - Broken link to [non-existent.md]
+  • docs/deployment.md:23 - Unreplaced placeholder {{DEPLOYMENT_STEPS}}
+```
+
+### Detailed Report
+
+For each documentation file:
+- **Filename and path**
+- **Score breakdown** (Freshness + Completeness + Quality)
+- **Last Updated**: Timestamp
+- **Specific Issues**: With line numbers
+- **Recommendations**: Actionable next steps with commands
+
+## Recommendations Format
+
+Based on findings, suggest specific actions:
+
+```
+Priority Recommendations:
+
+1. HIGH: Update data model documentation
+   Command: /docs:diagram er
+   Reason: Schema changed 5 days ago, ER diagram missing
+
+2. MEDIUM: Fix deployment documentation placeholders
+   Command: /docs:update deployment
+   Reason: Contains unreplaced placeholders
+
+3. LOW: Add security documentation
+   Command: /docs:diagram security
+   Reason: Good practice for complete documentation
+```
+
+## Important Notes
+
+- **Non-destructive**: Only reads, never modifies documentation
+- **Git-aware**: Uses git history to assess freshness
+- **Context-aware**: Understands project type and relevant docs
+- **Actionable**: Provides specific commands to fix issues
+- **Incremental**: Can be run frequently
+
+## Example Checks
+
+### Core Documentation
+- architecture.md exists and current?
+- onboarding.md exists and comprehensive?
+- ADRs directory exists with properly formatted ADRs?
+
+### Data Documentation
+- data-model.md exists if database detected?
+- ER diagrams present and valid?
+- Schema matches current models?
+
+### Infrastructure Documentation
+- deployment.md exists if Docker/K8s detected?
+- Security.md exists?
+- Dependencies documented?
+
+## When to Run
+
+Run this command:
+- Before onboarding new team members
+- During documentation reviews
+- After major refactoring
+- As part of pre-release checklist
+- When documentation feels stale
+- Regularly (weekly or bi-weekly)
+
+## Best Practices
+
+- **Run regularly**: Make it part of your workflow
+- **Address issues**: Don't let documentation debt accumulate
+- **Automate**: Consider running in CI for documentation PRs
+- **Prioritize**: Fix high-impact issues first
+- **Track scores**: Monitor documentation health over time
+
+---
+
+**Dependencies**: Requires git for freshness checking
+**Output**: Comprehensive health report with scores and recommendations