Initial commit

2025-11-30 08:31:57 +08:00
commit aebfdd53e0
10 changed files with 2177 additions and 0 deletions
--- a/commands/help.md
+++ b/commands/help.md
@@ -0,0 +1,667 @@
+---
+description: Documentation review system help - usage guide and command reference
+allowed-tools: Bash(cat:*)
+---
+
+# 📚 Documentation Review System - Help Guide
+
+**Version:** Phase 3 (Modular Architecture)
+**Last Updated:** 2025-10-24
+
+---
+
+## 🎯 What Is This?
+
+The `/ck:doc-review` system is a **modular documentation update toolkit** that
+helps you:
+
+✅ Keep documentation in sync with code changes
+✅ Update README, CLAUDE.md, CHANGELOG consistently
+✅ Maintain SDD (Specification-Driven Development) artifacts
+✅ Validate documentation quality before commits
+✅ Save 88% tokens compared to manual updates
+
+---
+
+## 🏗️ Architecture Overview
+
+```text
+┌─────────────────────────────────────────┐
+│ /ck:doc-review (Orchestrator)           │
+│ • Analyzes changes                      │
+│ • Asks what to update                   │
+│ • Delegates to sub-commands             │
+│ • Shows summary                         │
+└─────────────────────────────────────────┘
+           │
+    ┌──────┼──────┬──────┬──────┐
+    ▼      ▼      ▼      ▼      ▼
+┌────────┐ │  │  │  │  │  │  └─────────┐
+│:analyze│ │:core│ │:sdd│ │:qa│ │:help  │
+│        │ │     │ │    │ │   │ │       │
+│ 0 edits│ │3 files││SDD │ │Check││This!│
+└────────┘ └─────┘ └────┘ └────┘ └──────┘
+```
+
+---
+
+## 📋 Command Reference
+
+### `/ck:doc-review/help` (This Command)
+
+**Purpose:** Show help and usage guide
+**Token Cost:** ~200 tokens (one-time)
+**Files Modified:** None
+**Use When:** First time using system, or need reminder
+
+---
+
+### `/ck:doc-review/analyze`
+
+**Purpose:** Analyze documentation needs without making changes
+**Token Cost:** ~600-800 tokens
+**Files Modified:** None
+**Execution Time:** < 1 second
+
+**What It Does:**
+
+- ✅ Detects project documentation principles
+- ✅ Analyzes current documentation structure
+- ✅ Identifies what needs updating (from git history)
+- ✅ Provides actionable recommendations
+- ❌ Makes zero changes
+
+**When to Use:**
+
+- "What docs need updating?"
+- Before starting documentation work
+- Quick health check
+- Understanding project doc structure
+
+**Example:**
+
+```bash
+/ck:doc-review/analyze
+
+→ Output:
+  - 61 .md files found
+  - Recent changes: 5 files in src/
+  - Recommendations: Update README, CLAUDE, specs/005/
+  - Execution: 0.8s
+```
+
+---
+
+### `/ck:doc-review/core`
+
+**Purpose:** Update core documentation files
+**Token Cost:** ~1,200-1,500 tokens
+**Files Modified:** README.md, CLAUDE.md, CHANGELOG.md
+**Execution Time:** 15-30 seconds
+
+**What It Does:**
+
+- ✅ Updates README.md (features, usage, installation)
+- ✅ Updates CLAUDE.md (AI context, module docs)
+- ✅ Updates CHANGELOG.md (version entry)
+- ✅ Uses professional templates
+- ✅ Validates changes
+
+**When to Use:**
+
+- Just added a new feature
+- Need to document new API/module
+- Quick documentation update
+- Before sharing project
+
+**Example:**
+
+```bash
+/ck:doc-review/core "ApstraWorkModule implementation"
+
+→ Updates:
+  - README.md: Added usage examples
+  - CLAUDE.md: Added module context
+  - CHANGELOG.md: Created v1.2.0 entry
+  - Time: 18s
+```
+
+**Templates Provided:**
+
+- README feature section
+- CLAUDE module documentation
+- CHANGELOG version entry
+
+---
+
+### `/ck:doc-review/sdd`
+
+**Purpose:** Update SDD (Specification-Driven Development) artifacts
+**Token Cost:** ~1,500-1,800 tokens
+**Files Modified:** specs/_/spec.md, plan.md, tasks.md, contracts/_.md
+**Execution Time:** 30-60 seconds
+
+**What It Does:**
+
+- ✅ Marks requirements (FR-\*) as completed in spec.md
+- ✅ Updates implementation plan and phase status in plan.md
+- ✅ Marks tasks complete and adds notes in tasks.md
+- ✅ Updates design contracts and API specs
+- ✅ Validates SDD ↔ code consistency
+
+**When to Use:**
+
+- Completed an implementation phase
+- Need to sync specs with code
+- Mark requirements as done
+- Document architecture decisions
+
+**Example:**
+
+```bash
+/ck:doc-review/sdd "Phase 2 completion"
+
+→ Updates:
+  - spec.md: Marked FR-005-1, FR-005-2 complete
+  - plan.md: Phase 2 status = ✅ Completed
+  - tasks.md: 15 tasks marked done
+  - Consistency: 100%
+  - Time: 42s
+```
+
+**SDD Consistency Checks:**
+
+- Requirements → Implementation alignment
+- Plan → Tasks alignment
+- Contracts → Code alignment
+- Traceability validation
+
+---
+
+### `/ck:doc-review/qa`
+
+**Purpose:** Quality assurance - validate documentation
+**Token Cost:** ~1,800-2,000 tokens
+**Files Modified:** None
+**Execution Time:** 10-20 seconds
+
+**What It Does:**
+
+- ✅ Validates markdown links (finds broken links)
+- ✅ Checks file:line references (path/to/file.py:123)
+- ✅ Checks terminology consistency
+- ✅ Validates version number consistency
+- ✅ Checks SDD requirement traceability
+- ✅ Basic code example syntax validation
+- ✅ Completeness check (required sections)
+- ✅ Generates scored report (0-100)
+
+**When to Use:**
+
+- Before committing documentation changes
+- After major documentation updates
+- Find and fix broken links
+- Ensure documentation quality
+
+**Example:**
+
+```bash
+/ck:doc-review/qa
+
+→ Results:
+  - Valid links: 156
+  - Broken links: 3
+  - Version mismatches: 1
+  - Overall score: 87/100
+  - Time: 12s
+
+→ Recommendations:
+  1. Fix broken link in README.md:45
+  2. Update version in pyproject.toml
+```
+
+**QA Categories:**
+
+1. Link Validation (20 points)
+2. Cross-Reference Validation (15 points)
+3. Terminology Consistency (15 points)
+4. Version Consistency (15 points)
+5. SDD Consistency (15 points)
+6. Code Example Quality (10 points)
+7. Completeness (10 points)
+
+---
+
+### `/ck:doc-review` (Main Orchestrator)
+
+**Purpose:** Smart orchestration - analyze and delegate
+**Token Cost:** ~900-1,200 tokens (orchestrator only) + selected sub-commands
+**Files Modified:** Depends on user selection
+**Execution Time:** Variable (depends on selection)
+
+**What It Does:**
+
+- ✅ Runs comprehensive analysis (via doc-analyzer.sh)
+- ✅ Shows analysis summary
+- ✅ Asks user which areas to update
+- ✅ Invokes selected sub-commands automatically
+- ✅ Aggregates and shows summary
+
+**When to Use:**
+
+- Not sure what needs updating
+- Want guided workflow
+- Comprehensive documentation update
+- First time using the system
+
+**Example:**
+
+```bash
+/ck:doc-review "feature 005 implementation"
+
+→ Analysis shown (principles, structure, changes, metrics)
+
+→ User asked:
+  Which areas to update?
+  □ Core Files (README, CLAUDE, CHANGELOG)
+  □ SDD Artifacts (spec, plan, tasks)
+  □ Run QA Only
+  □ Full Update
+
+→ User selects "Full Update"
+
+→ Executes:
+  1. /ck:doc-review/core "feature 005"
+  2. /ck:doc-review/sdd "feature 005"
+  3. /ck:doc-review/qa
+
+→ Aggregated summary:
+  - 8 files updated
+  - QA score: 92/100
+  - Total time: 78s
+```
+
+---
+
+## 🎓 Usage Patterns
+
+### Pattern 1: Quick README Update (Most Common)
+
+```bash
+# Scenario: Added new feature, need docs
+/ck:doc-review/core "new feature name"
+
+# Time: 20s
+# Token: 1.2K
+# Updates: README, CLAUDE, CHANGELOG
+```
+
+### Pattern 2: Analysis First (Recommended for New Users)
+
+```bash
+# Step 1: Understand what needs updating
+/ck:doc-review/analyze
+
+# Step 2: Update based on recommendations
+/ck:doc-review/core "feature X"
+
+# Time: 1s + 20s = 21s
+# Tokens: 600 + 1.2K = 1.8K
+```
+
+### Pattern 3: Full Update After Major Work
+
+```bash
+# Completed major implementation
+/ck:doc-review "Phase 2 complete"
+
+→ Select "Full Update"
+→ All docs updated + QA validated
+
+# Time: 60-90s
+# Tokens: 3-4K
+# Updates: Everything
+```
+
+### Pattern 4: QA Before Commit (Best Practice)
+
+```bash
+# Before git commit
+/ck:doc-review/qa
+
+→ Fix any issues found
+→ Re-run QA
+→ Commit with confidence
+
+# Time: 10-15s per run
+# Tokens: 1.8K
+```
+
+### Pattern 5: SDD Update After Phase
+
+```bash
+# Completed implementation phase
+/ck:doc-review/sdd "Phase 2"
+
+# Time: 40-50s
+# Tokens: 1.5K
+# Updates: All SDD artifacts
+```
+
+---
+
+## 🗂️ File Structure Reference
+
+### Command Files Location
+
+```text
+~/.claude/commands/ck/
+├── doc-review.md              # Main orchestrator
+├── doc-review:analyze.md      # Analysis only
+├── doc-review:core.md         # Core files update
+├── doc-review:sdd.md          # SDD artifacts update
+├── doc-review:qa.md           # Quality validation
+├── doc-review:help.md         # This help file
+└── doc-categories.json        # Pattern configuration
+```
+
+### Supporting Tools
+
+```text
+~/.claude/tools/
+└── doc-analyzer.sh            # External analysis script
+    ├── principles             # Extract doc principles
+    ├── structure              # Analyze doc structure
+    ├── categorize             # Categorize files
+    ├── impact                 # Assess change impact
+    ├── metrics                # Generate metrics
+    └── all                    # Run all analyses
+```
+
+### Documentation
+
+```text
+docs/
+├── ck-doc-review-analysis.md            # Architecture analysis
+├── ck-doc-review-phase1-improvements.md # Phase 1 docs
+├── ck-doc-review-phase2-improvements.md # Phase 2 docs
+└── ck-doc-review-phase3-improvements.md # Phase 3 docs (current)
+```
+
+---
+
+## 📊 Token Budgeting
+
+### Per-Command Token Costs
+
+| Command      | Tokens                   | Use Case           |
+| ------------ | ------------------------ | ------------------ |
+| `:help`      | ~200                     | One-time reference |
+| `:analyze`   | ~600-800                 | Analysis only      |
+| `:core`      | ~1.2-1.5K                | Quick update       |
+| `:sdd`       | ~1.5-1.8K                | SDD update         |
+| `:qa`        | ~1.8-2K                  | Quality check      |
+| `doc-review` | ~900-1.2K + sub-commands | Full orchestration |
+
+### Monthly Token Budget Examples
+
+**Light Usage (10 updates/month):**
+
+```plaintext
+10x :core updates: 12-15K tokens
+2x :qa checks: 3.6-4K tokens
+1x :help reference: 200 tokens
+Total: ~16-19K tokens/month
+```
+
+**Medium Usage (20 updates/month):**
+
+```plaintext
+15x :core updates: 18-22.5K tokens
+4x :sdd updates: 6-7.2K tokens
+4x :qa checks: 7.2-8K tokens
+1x :help reference: 200 tokens
+Total: ~31-38K tokens/month
+```
+
+**Heavy Usage (40 updates/month):**
+
+```plaintext
+25x :core updates: 30-37.5K tokens
+8x :sdd updates: 12-14.4K tokens
+8x :qa checks: 14.4-16K tokens
+4x orchestrated: 12-16K tokens
+1x :help reference: 200 tokens
+Total: ~69-84K tokens/month
+```
+
+**Original System (Same Usage):**
+
+```
+40x monolithic commands: 400-480K tokens/month
+Savings with Phase 3: 83-93%
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### "Command not found: /ck:doc-review/core"
+
+**Cause:** Sub-command file not installed
+**Solution:**
+
+```bash
+# Check if files exist
+ls ~/.claude/commands/ck/doc-review*.md
+
+# Should see all sub-command files
+# If missing, reinstall from docs
+```
+
+---
+
+### "Analysis fails with error"
+
+**Cause:** doc-analyzer.sh not executable or not found
+**Solution:**
+
+```bash
+# Check if tool exists
+ls -l ~/.claude/tools/doc-analyzer.sh
+
+# Make executable
+chmod +x ~/.claude/tools/doc-analyzer.sh
+
+# Test manually
+~/.claude/tools/doc-analyzer.sh help
+```
+
+---
+
+### "QA reports many broken links"
+
+**Cause:** Links broken after file reorganization
+**Solution:**
+
+```bash
+# Run QA to identify broken links
+/ck:doc-review/qa
+
+# Fix links in reported files
+# Re-run QA to verify
+/ck:doc-review/qa
+```
+
+---
+
+### "SDD consistency check fails"
+
+**Cause:** Requirements/tasks out of sync with code
+**Solution:**
+
+```bash
+# Update SDD artifacts
+/ck:doc-review/sdd "current feature"
+
+# Manually review any remaining inconsistencies
+# Update as needed
+```
+
+---
+
+## 💡 Tips & Best Practices
+
+### 1. Run `:analyze` First (New Projects)
+
+```bash
+# When starting with a new project
+/ck:doc-review/analyze
+
+→ Understand doc structure
+→ Identify gaps
+→ Plan updates
+```
+
+### 2. Use `:core` for Quick Updates
+
+```bash
+# Daily workflow: added feature, need docs
+/ck:doc-review/core "feature name"
+
+→ Fast (20s)
+→ Low token cost (1.2K)
+→ Updates essentials
+```
+
+### 3. Run `:qa` Before Commits
+
+```bash
+# Git workflow
+git add .
+/ck:doc-review/qa    # Check doc quality
+→ Fix any issues
+git commit -m "docs: ..."
+```
+
+### 4. Use Orchestrator When Unsure
+
+```bash
+# Not sure what needs updating?
+/ck:doc-review "what changed"
+
+→ Guided workflow
+→ Smart recommendations
+→ You choose scope
+```
+
+### 5. Batch SDD Updates
+
+```bash
+# Don't update SDD after every task
+# Batch at phase boundaries
+/ck:doc-review/sdd "Phase 2 complete"
+
+→ More efficient
+→ Better overview
+→ Cleaner commits
+```
+
+---
+
+## 🎯 Decision Tree: Which Command to Use?
+
+```text
+Start
+  │
+  ├─ Need help? → /ck:doc-review/help
+  │
+  ├─ Just want to see what needs updating?
+  │  └─ /ck:doc-review/analyze
+  │
+  ├─ Added new feature/module?
+  │  └─ /ck:doc-review/core "feature name"
+  │
+  ├─ Completed implementation phase?
+  │  └─ /ck:doc-review/sdd "phase name"
+  │
+  ├─ About to commit documentation?
+  │  └─ /ck:doc-review/qa
+  │
+  ├─ Not sure what to do?
+  │  └─ /ck:doc-review "what changed"
+  │
+  └─ Want comprehensive update?
+     └─ /ck:doc-review "scope" → Select "Full Update"
+```
+
+---
+
+## 📚 Further Reading
+
+**Architecture Deep Dive:**
+
+- `docs/ck-doc-review-analysis.md` - Initial architecture analysis
+- `docs/ck-doc-review-phase3-improvements.md` - Current system design
+
+**Phase Evolution:**
+
+- Phase 1: Progressive disclosure + patterns config
+- Phase 2: External tool architecture
+- Phase 3: Full modularization (current)
+
+**External Tools:**
+
+- `~/.claude/tools/doc-analyzer.sh help` - Tool documentation
+- Run `doc-analyzer.sh all` to see full analysis output
+
+---
+
+## 🆘 Getting Help
+
+### Within the System
+
+```bash
+/ck:doc-review/help              # This guide
+~/.claude/tools/doc-analyzer.sh help  # Tool help
+```
+
+### Documentation Files
+
+```bash
+cat docs/ck-doc-review-phase3-improvements.md  # Full system docs
+```
+
+### Quick Reference Card
+
+```bash
+# Analysis
+/ck:doc-review/analyze
+
+# Updates
+/ck:doc-review/core "feature"    # Quick
+/ck:doc-review/sdd "phase"       # SDD
+/ck:doc-review "scope"           # Full
+
+# Validation
+/ck:doc-review/qa
+
+# Help
+/ck:doc-review/help
+```
+
+---
+
+## ✨ Key Takeaways
+
+1. **Modular = Efficient** - Use focused commands, not monolithic tool
+2. **Analyze First** - Understand before updating
+3. **Core for Speed** - Most common use case
+4. **QA Before Commit** - Catch issues early
+5. **Orchestrate When Unsure** - Guided workflow helps
+
+---
+
+**Last Updated:** 2025-10-24
+**Version:** Phase 3 (Modular Architecture)
+**System Status:** Production Ready ✅