gh-kimcharli-ck-skills-plugins-doc-review-commands/commands/help.md

description, allowed-tools

description	allowed-tools
Documentation review system help - usage guide and command reference	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

┌─────────────────────────────────────────┐
│ /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:

/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:

/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:

/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:

/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:

/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)

# 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)

# 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

# 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)

# 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

# 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

~/.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

~/.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

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):

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):

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):

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:

# 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:

# 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:

# 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:

# 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)

# When starting with a new project
/ck:doc-review/analyze

→ Understand doc structure
→ Identify gaps
→ Plan updates

2. Use :core for Quick Updates

# 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

# Git workflow
git add .
/ck:doc-review/qa    # Check doc quality
→ Fix any issues
git commit -m "docs: ..."

4. Use Orchestrator When Unsure

# Not sure what needs updating?
/ck:doc-review "what changed"

→ Guided workflow
→ Smart recommendations
→ You choose scope

5. Batch SDD Updates

# 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?

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

/ck:doc-review/help              # This guide
~/.claude/tools/doc-analyzer.sh help  # Tool help

Documentation Files

cat docs/ck-doc-review-phase3-improvements.md  # Full system docs

Quick Reference Card

# 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 ✅