Initial commit
This commit is contained in:
Zhongwei Li
124
commands/analyze.md
Normal file
124
commands/analyze.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
|
||||
description: Run documentation analysis without making changes
|
||||
allowed-tools: Bash(~/.claude/commands/ck/doc-review/tools/analyzer.sh:*), Bash(~/.claude/tools/doc-analyzer.sh:*)
|
||||
---
|
||||
|
||||
# Documentation Analysis Command
|
||||
|
||||
## Context
|
||||
|
||||
- Analysis Results:
|
||||
!`~/.claude/commands/ck/doc-review/tools/analyzer.sh all || ~/.claude/tools/doc-analyzer.sh all`
|
||||
|
||||
## Task
|
||||
|
||||
**Analysis-only mode** - Review project documentation without making changes.
|
||||
|
||||
---
|
||||
|
||||
## Analysis Summary
|
||||
|
||||
Present the analysis results in a user-friendly format:
|
||||
|
||||
### 📋 Project Documentation Principles
|
||||
|
||||
[Summarize principles detected from analysis output above]
|
||||
|
||||
**Detected Constraints:**
|
||||
|
||||
- [List any detected principles or "None detected"]
|
||||
|
||||
**Impact:** [Explain what this means for documentation updates]
|
||||
|
||||
---
|
||||
|
||||
### 📁 Documentation Structure
|
||||
|
||||
**Inventory:**
|
||||
|
||||
- Total .md files: [from metrics]
|
||||
- Root directory: [count]
|
||||
- docs/ directory: [count]
|
||||
- specs/ directory: [count]
|
||||
|
||||
**Organization Assessment:**
|
||||
|
||||
- [Summarize if current structure is good or needs reorganization]
|
||||
- [List any potential improvements]
|
||||
|
||||
---
|
||||
|
||||
### 🎯 Change Impact Assessment
|
||||
|
||||
**Recent Changes:**
|
||||
[List files changed from git analysis]
|
||||
|
||||
**Documentation Impact:**
|
||||
|
||||
- README.md: [Needs update? Why?]
|
||||
- CLAUDE.md: [Needs update? Why?]
|
||||
- SDD artifacts: [Needs update? Why?]
|
||||
- API/Technical docs: [Needs update? Why?]
|
||||
|
||||
**Recommended Actions:**
|
||||
|
||||
1. [Prioritized list of documentation updates needed]
|
||||
2. [...]
|
||||
|
||||
---
|
||||
|
||||
### 📊 Current Metrics
|
||||
|
||||
**Documentation Health:**
|
||||
|
||||
- Total documentation lines: [from metrics]
|
||||
- Last commit: [from git]
|
||||
- Last doc update: [from git]
|
||||
|
||||
**Quality Indicators:**
|
||||
|
||||
- Large files (>200 lines): [count and list]
|
||||
- Potential misplaced files: [count and list]
|
||||
- SDD coverage: [number of active specs]
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
Based on this analysis, here's what you should do:
|
||||
|
||||
### High Priority
|
||||
|
||||
- [List high-priority updates]
|
||||
|
||||
### Medium Priority
|
||||
|
||||
- [List medium-priority updates]
|
||||
|
||||
### Low Priority / Optional
|
||||
|
||||
- [List optional improvements]
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
**To update documentation, use:**
|
||||
|
||||
- `/ck:doc-review/core [feature]` - Update core files
|
||||
- `/ck:doc-review/sdd [feature]` - Update SDD artifacts
|
||||
- `/ck:doc-review/main [feature]` - Full update with user choice
|
||||
|
||||
**To validate quality:**
|
||||
|
||||
- `/ck:doc-review/qa` - Run quality checks
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
✅ **No Changes Made** - Safe to run anytime
|
||||
✅ **Fast** - Completes in < 1 second
|
||||
✅ **Comprehensive** - Full picture of doc health
|
||||
✅ **Actionable** - Clear next steps
|
||||
210
commands/core.md
Normal file
210
commands/core.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
|
||||
description: Update core documentation files (README, CLAUDE, CHANGELOG)
|
||||
allowed-tools: Bash(cat:*), Bash(git:*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
|
||||
---
|
||||
|
||||
# Core Documentation Update Command
|
||||
|
||||
## Context
|
||||
|
||||
- Config:
|
||||
!`cat ~/.claude/commands/ck/doc-review/config/categories.json`
|
||||
- Recent changes:
|
||||
!`git diff --name-only HEAD~5..HEAD 2>/dev/null || echo "No recent commits"`
|
||||
|
||||
## Task
|
||||
|
||||
**Update core documentation for:** $ARGUMENTS
|
||||
|
||||
**Files to update:**
|
||||
|
||||
- README.md
|
||||
- CLAUDE.md
|
||||
- CHANGELOG.md
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Read Current Files
|
||||
|
||||
Read the current state of core files to understand what needs updating.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: README.md Updates
|
||||
|
||||
### What to Update
|
||||
|
||||
Based on $ARGUMENTS, update relevant sections:
|
||||
|
||||
**Features Section:**
|
||||
If new feature added, use this template:
|
||||
|
||||
````markdown
|
||||
|
||||
### [Feature Name]
|
||||
|
||||
Brief description of what it does and why it's useful.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```[language]
|
||||
# Code example here
|
||||
```
|
||||
````
|
||||
|
||||
**Key Features:**
|
||||
|
||||
- Feature point 1
|
||||
- Feature point 2
|
||||
|
||||
````
|
||||
|
||||
**Installation Section:**
|
||||
- Update if new dependencies added
|
||||
- Update if setup process changed
|
||||
- Verify all steps still work
|
||||
|
||||
**Configuration Section:**
|
||||
- Add new configuration options
|
||||
- Update examples with new settings
|
||||
- Note any breaking changes
|
||||
|
||||
**Troubleshooting:**
|
||||
- Add common issues encountered during development
|
||||
- Document solutions/workarounds
|
||||
|
||||
### Make Updates
|
||||
|
||||
Apply updates to README.md using Edit tool.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: CLAUDE.md Updates
|
||||
|
||||
### What to Update
|
||||
|
||||
Add AI assistant context for: $ARGUMENTS
|
||||
|
||||
**Use this template:**
|
||||
|
||||
````markdown
|
||||
### [Module/Feature Name]
|
||||
- **Purpose**: [What it does in one sentence]
|
||||
- **Location**: `path/to/file.py:123`
|
||||
- **Key Components**:
|
||||
- `ClassName` - Description
|
||||
- `function_name()` - Description
|
||||
- **Usage Pattern**:
|
||||
```bash
|
||||
# Example usage
|
||||
```
|
||||
````
|
||||
|
||||
- **Error Handling**:
|
||||
- Common error 1: Solution
|
||||
- Common error 2: Solution
|
||||
- **Related Components**: [Links to related sections]
|
||||
|
||||
````
|
||||
|
||||
**Additional Context:**
|
||||
- Update architecture overview if structure changed
|
||||
- Add new workflow patterns
|
||||
- Document design decisions
|
||||
- Add debugging tips
|
||||
|
||||
### Make Updates
|
||||
|
||||
Apply updates to CLAUDE.md using Edit tool.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: CHANGELOG.md Updates
|
||||
|
||||
### Determine Version
|
||||
|
||||
Check current version and determine if this is:
|
||||
- Patch (bug fix): increment 0.0.X
|
||||
- Minor (new feature): increment 0.X.0
|
||||
- Major (breaking change): increment X.0.0
|
||||
|
||||
### Use Template
|
||||
|
||||
````markdown
|
||||
## [Version] - YYYY-MM-DD
|
||||
|
||||
### Added
|
||||
- Feature: [description] (file.py:123)
|
||||
- Feature: [description]
|
||||
|
||||
### Changed
|
||||
- Modified: [description]
|
||||
- Updated: [description]
|
||||
|
||||
### Fixed
|
||||
- Bug: [description] (#issue)
|
||||
- Issue: [description]
|
||||
|
||||
### Deprecated
|
||||
- [What's being removed in future]
|
||||
````
|
||||
|
||||
### Make Updates
|
||||
|
||||
- Read current CHANGELOG.md
|
||||
- Add new entry at the top (most recent first)
|
||||
- Use Edit tool to update
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Validation
|
||||
|
||||
**Check Updates:**
|
||||
|
||||
- [ ] README.md updated with new feature/changes
|
||||
- [ ] CLAUDE.md has AI context for new components
|
||||
- [ ] CHANGELOG.md has version entry with categorized changes
|
||||
- [ ] All code examples are syntactically correct
|
||||
- [ ] File:line references are accurate
|
||||
- [ ] No sensitive information exposed
|
||||
|
||||
---
|
||||
|
||||
## Output: Summary
|
||||
|
||||
### 📊 Core Documentation Update Summary
|
||||
|
||||
**Scope:** $ARGUMENTS
|
||||
|
||||
**Files Updated:**
|
||||
|
||||
| File | Sections Modified | Lines Changed |
|
||||
| ------------ | ----------------- | ------------- |
|
||||
| README.md | [list sections] | ~[estimate] |
|
||||
| CLAUDE.md | [list sections] | ~[estimate] |
|
||||
| CHANGELOG.md | [version entry] | ~[estimate] |
|
||||
|
||||
**Key Changes:**
|
||||
|
||||
- [Bullet point summary of main changes]
|
||||
|
||||
**Validation:**
|
||||
|
||||
- [x] All core files updated
|
||||
- [x] Examples tested
|
||||
- [x] No sensitive data
|
||||
- [x] References accurate
|
||||
|
||||
**Execution Time:** [X]s
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
Recommended follow-up:
|
||||
|
||||
- [ ] Review changes: `git diff README.md CLAUDE.md CHANGELOG.md`
|
||||
- [ ] Test any code examples added
|
||||
- [ ] Update SDD if needed: `/ck:doc-review/sdd $ARGUMENTS`
|
||||
- [ ] Run QA: `/ck:doc-review/qa`
|
||||
667
commands/help.md
Normal file
667
commands/help.md
Normal file
@@ -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 ✅
|
||||
137
commands/main.md
Normal file
137
commands/main.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
|
||||
description: Documentation update orchestrator - analyzes and delegates to sub-commands
|
||||
allowed-tools: Bash(~/.claude/commands/ck/doc-review/tools/analyzer.sh:*), Bash(~/.claude/tools/doc-analyzer.sh:*), Read(*), SlashCommand(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
# Documentation Update Orchestrator
|
||||
|
||||
## Context
|
||||
|
||||
- Analysis:
|
||||
!`~/.claude/commands/ck/doc-review/tools/analyzer.sh all || ~/.claude/tools/doc-analyzer.sh all`
|
||||
|
||||
## Task
|
||||
|
||||
**Update all documentation for:** $ARGUMENTS
|
||||
|
||||
**🎯 Smart Orchestration:** This command analyzes your changes and delegates to sub-commands.
|
||||
|
||||
---
|
||||
|
||||
## Analysis Review
|
||||
|
||||
Review the analysis output above to understand:
|
||||
|
||||
✅ **Principles:** Project documentation constraints (if any)
|
||||
✅ **Structure:** Current documentation organization
|
||||
✅ **Changes:** Files modified in recent commits
|
||||
✅ **Impact:** Which documentation needs updating
|
||||
|
||||
---
|
||||
|
||||
## Recommended Update Plan
|
||||
|
||||
Based on the analysis, here's what needs updating:
|
||||
|
||||
**Available Sub-Commands:**
|
||||
|
||||
- `/ck:doc-review/quick` - Fast updates, no analysis (~400-600 tokens)
|
||||
- `/ck:doc-review/analyze` - Run analysis only (no updates)
|
||||
- `/ck:doc-review/core` - Update README, CLAUDE, CHANGELOG
|
||||
- `/ck:doc-review/sdd` - Update SDD artifacts (spec.md, plan.md, tasks.md)
|
||||
- `/ck:doc-review/qa` - Quality validation and link checking
|
||||
|
||||
---
|
||||
|
||||
## User Confirmation
|
||||
|
||||
Use AskUserQuestion to ask:
|
||||
|
||||
### Question: Which documentation should be updated?
|
||||
|
||||
**header:** "Update Scope"
|
||||
**question:** "Which documentation areas should be updated for: $ARGUMENTS"
|
||||
**multiSelect:** true
|
||||
**options:**
|
||||
|
||||
- **label:** "Core Files"
|
||||
**description:** "README.md, CLAUDE.md, CHANGELOG.md - Quick updates (1-2 min)"
|
||||
|
||||
- **label:** "SDD Artifacts"
|
||||
**description:** "specs/\*/spec.md, plan.md, tasks.md - Specification updates (2-3 min)"
|
||||
|
||||
- **label:** "Run QA Only"
|
||||
**description:** "Link validation, consistency checks - No content changes"
|
||||
|
||||
- **label:** "Full Update"
|
||||
**description:** "All documentation areas - Comprehensive update (3-5 min)"
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
Based on user selection, invoke appropriate sub-commands:
|
||||
|
||||
### If "Core Files" selected
|
||||
|
||||
```bash
|
||||
/ck:doc-review/core $ARGUMENTS
|
||||
```
|
||||
|
||||
### If "SDD Artifacts" selected
|
||||
|
||||
```bash
|
||||
/ck:doc-review/sdd $ARGUMENTS
|
||||
```
|
||||
|
||||
### If "Run QA Only" selected
|
||||
|
||||
```bash
|
||||
/ck:doc-review/qa
|
||||
```
|
||||
|
||||
### If "Full Update" selected
|
||||
|
||||
```bash
|
||||
/ck:doc-review/core $ARGUMENTS
|
||||
/ck:doc-review/sdd $ARGUMENTS
|
||||
/ck:doc-review/qa
|
||||
```
|
||||
|
||||
**⚠️ Note:** Run sub-commands sequentially, wait for each to complete before running the next.
|
||||
|
||||
---
|
||||
|
||||
## Final Summary
|
||||
|
||||
After all sub-commands complete, provide aggregated summary:
|
||||
|
||||
### 📊 Complete Documentation Update Summary
|
||||
|
||||
**Scope:** $ARGUMENTS
|
||||
|
||||
**Sub-Commands Executed:**
|
||||
|
||||
- [List which sub-commands ran]
|
||||
|
||||
**Total Updates:**
|
||||
|
||||
- Files modified: [aggregate count]
|
||||
- Total time: [sum of execution times]
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
- [ ] Review changes: `git diff`
|
||||
- [ ] Commit updates: `git add . && git commit -m "docs: ..."`
|
||||
- [ ] Push if ready: `git push`
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Modular Approach
|
||||
|
||||
✅ **90% Token Reduction** - Only load what you need
|
||||
✅ **Faster Execution** - Focused commands run in < 1s
|
||||
✅ **Clear Responsibility** - Each command does one thing well
|
||||
✅ **Reusable** - Use sub-commands independently
|
||||
✅ **Composable** - Mix and match as needed
|
||||
480
commands/qa.md
Normal file
480
commands/qa.md
Normal file
@@ -0,0 +1,480 @@
|
||||
---
|
||||
|
||||
description: Quality validation - auto-fix linting, check links, consistency, completeness
|
||||
allowed-tools: Bash(find:*), Bash(grep:*), Bash(git:*), Bash(npm:*), Read(*), Grep(*), Glob(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
# Quality Assurance Validation Command
|
||||
|
||||
## Context
|
||||
|
||||
- All markdown files: !`find . -name "*.md" | wc -l`
|
||||
- Recent doc changes:
|
||||
!`git log -5 --oneline -- "*.md" 2>/dev/null || echo "No recent doc commits"`
|
||||
|
||||
## Task
|
||||
|
||||
**Quality validation and auto-fix** - Automatically fixes formatting issues with
|
||||
linting tools, then performs validation checks for links, consistency, and
|
||||
completeness.
|
||||
|
||||
---
|
||||
|
||||
## Linting & Auto-Fix Phase
|
||||
|
||||
### Step 1: Check for Linting Tools
|
||||
|
||||
```bash
|
||||
# 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"
|
||||
```
|
||||
|
||||
### Step 2: Install Tools if Missing
|
||||
|
||||
If tools are not available:
|
||||
|
||||
```bash
|
||||
npm install -g markdownlint-cli prettier
|
||||
```
|
||||
|
||||
### Step 3: Auto-Fix Markdown Files
|
||||
|
||||
**Run markdownlint with auto-fix enabled:**
|
||||
|
||||
```bash
|
||||
markdownlint --fix . --ignore node_modules --ignore '.git'
|
||||
```
|
||||
|
||||
This automatically fixes:
|
||||
|
||||
- MD032: Lists surrounded by blank lines
|
||||
- MD034: Bare URLs wrapped in links
|
||||
- MD036: Emphasis used instead of headings
|
||||
- MD040: Fenced code blocks with language specified
|
||||
- MD059: Link text descriptive
|
||||
|
||||
**Run prettier for consistent formatting:**
|
||||
|
||||
```bash
|
||||
prettier --write "**/*.md"
|
||||
```
|
||||
|
||||
This formats:
|
||||
|
||||
- Line length consistency
|
||||
- Indentation
|
||||
- List formatting
|
||||
- Code block formatting
|
||||
|
||||
### Step 4: Verify Changes
|
||||
|
||||
```bash
|
||||
# Show what was changed
|
||||
git diff --name-only 2>/dev/null || echo "Not a git repo"
|
||||
|
||||
# Count auto-fixed issues
|
||||
echo "✅ Auto-fix complete"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 1: Link Validation
|
||||
|
||||
### Find All Markdown Links
|
||||
|
||||
Search for markdown links in all .md files:
|
||||
|
||||
```bash
|
||||
# Find all links
|
||||
find . -name "*.md" -exec grep -o '\[.*\](.*\.md)' {} +
|
||||
|
||||
# Find relative links
|
||||
find . -name "*.md" -exec grep -o '](\.\.*/.*\.md)' {} +
|
||||
```
|
||||
|
||||
### Validate Links
|
||||
|
||||
For each link found:
|
||||
|
||||
- Check if target file exists
|
||||
- Note broken links
|
||||
- Note external links (for manual review)
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
✅ Valid links: [count]
|
||||
❌ Broken links: [count]
|
||||
⚠️ External links: [count] (manual review needed)
|
||||
|
||||
Broken Links Found:
|
||||
- file.md:123 → links to missing-file.md
|
||||
- [...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 2: Cross-Reference Consistency
|
||||
|
||||
### File:Line References
|
||||
|
||||
Find all code references (e.g., `path/to/file.py:123`):
|
||||
|
||||
```bash
|
||||
find . -name "*.md" -exec grep -o '[a-zA-Z0-9_/.-]*\.[a-z]*:[0-9]*' {} +
|
||||
```
|
||||
|
||||
### Validate References
|
||||
|
||||
For each reference:
|
||||
|
||||
- Check if file exists
|
||||
- Optionally check if line number is reasonable (file has that many lines)
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
✅ 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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 3: Terminology Consistency
|
||||
|
||||
### Extract Key Terms
|
||||
|
||||
Find variations of important terms:
|
||||
|
||||
```bash
|
||||
# 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")
|
||||
```
|
||||
|
||||
### Common Inconsistencies to Check
|
||||
|
||||
- Product names (capitalization)
|
||||
- Feature names (hyphenation)
|
||||
- Technical terms (spelling variations)
|
||||
- Version numbers (consistency)
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
📝 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 4: Version Number Consistency
|
||||
|
||||
### Find All Version References
|
||||
|
||||
```bash
|
||||
# Find version patterns
|
||||
grep -E "v?[0-9]+\.[0-9]+\.[0-9]+" . -r --include="*.md"
|
||||
grep -E "version.*[0-9]" . -r --include="*.md" -i
|
||||
```
|
||||
|
||||
### Check Consistency
|
||||
|
||||
- Same version mentioned in multiple places?
|
||||
- CHANGELOG.md version matches README.md?
|
||||
- pyproject.toml version matches documentation?
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
📊 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 5: SDD Consistency (if applicable)
|
||||
|
||||
### Check Requirement Traceability
|
||||
|
||||
Find all requirement IDs (FR-\*, NFR-\*):
|
||||
|
||||
```bash
|
||||
grep -E "(FR|NFR)-[0-9]+" . -r --include="*.md"
|
||||
```
|
||||
|
||||
### Validate Traceability
|
||||
|
||||
- Are requirements in spec.md referenced in plan.md?
|
||||
- Are completed requirements (✅) in spec.md also marked done in tasks.md?
|
||||
- Are all requirements accounted for?
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
🔍 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 6: Code Example Syntax
|
||||
|
||||
### Find Code Blocks
|
||||
|
||||
```bash
|
||||
# Find all code fences
|
||||
grep -E "^\`\`\`" . -r --include="*.md"
|
||||
```
|
||||
|
||||
### Basic Syntax Check
|
||||
|
||||
- Are code fences properly closed?
|
||||
- Is language specified (`python vs`)?
|
||||
- Look for obvious syntax errors in examples
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
💻 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QA Check 7: Completeness Check
|
||||
|
||||
### Required Sections
|
||||
|
||||
Check if standard files have expected sections:
|
||||
|
||||
**README.md:**
|
||||
|
||||
- [ ] Project description
|
||||
- [ ] Installation
|
||||
- [ ] Usage examples
|
||||
- [ ] Configuration
|
||||
- [ ] License
|
||||
|
||||
**CLAUDE.md:**
|
||||
|
||||
- [ ] Project overview
|
||||
- [ ] Core architecture
|
||||
- [ ] Key modules
|
||||
- [ ] Common workflows
|
||||
|
||||
**CHANGELOG.md:**
|
||||
|
||||
- [ ] Recent version entries
|
||||
- [ ] Categorized changes (Added/Changed/Fixed)
|
||||
- [ ] Dates
|
||||
|
||||
**Report Format:**
|
||||
|
||||
```text
|
||||
📋 Completeness Check:
|
||||
|
||||
README.md:
|
||||
- ✅ Has installation section
|
||||
- ✅ Has usage examples
|
||||
- ❌ Missing troubleshooting section
|
||||
|
||||
CLAUDE.md:
|
||||
- ✅ Has architecture overview
|
||||
- ⚠️ Core modules section is sparse
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output: QA Summary Report
|
||||
|
||||
### 📊 Documentation Quality Assurance Report
|
||||
|
||||
**Validation Date:** [YYYY-MM-DD]
|
||||
|
||||
---
|
||||
|
||||
### Auto-Fix Results
|
||||
|
||||
**Linting & Formatting Phase:**
|
||||
|
||||
- ✅ markdownlint: [X] issues auto-fixed
|
||||
- ✅ prettier: [X] files reformatted
|
||||
- Files modified: [list of files]
|
||||
- Time taken: < 1 second
|
||||
|
||||
**Common fixes applied:**
|
||||
|
||||
- Blank lines around lists (MD032)
|
||||
- Bare URLs wrapped in links (MD034)
|
||||
- Link text made descriptive (MD059)
|
||||
- Code blocks with language specified (MD040)
|
||||
- Emphasis replaced with headings (MD036)
|
||||
|
||||
---
|
||||
|
||||
### Overall Quality Score
|
||||
|
||||
**Baseline Score:** [X]/100 (before fixes)
|
||||
**After Fixes:** [X]/100 (after linting)
|
||||
|
||||
---
|
||||
|
||||
### Link Validation
|
||||
|
||||
- ✅ Valid links: [count]
|
||||
- ❌ Broken links: [count]
|
||||
- Score: [X]/20
|
||||
|
||||
### Cross-Reference Validation
|
||||
|
||||
- ✅ Valid references: [count]
|
||||
- ❌ Invalid references: [count]
|
||||
- Score: [X]/15
|
||||
|
||||
### Terminology Consistency
|
||||
|
||||
- Inconsistencies found: [count]
|
||||
- Score: [X]/15
|
||||
|
||||
### Version Consistency
|
||||
|
||||
- Matches found: [count]
|
||||
- Mismatches: [count]
|
||||
- Score: [X]/15
|
||||
|
||||
### SDD Consistency
|
||||
|
||||
- Orphaned requirements: [count]
|
||||
- Traceability: [X]%
|
||||
- Score: [X]/15
|
||||
|
||||
### Code Example Quality
|
||||
|
||||
- Syntax issues: [count]
|
||||
- Score: [X]/10
|
||||
|
||||
### Completeness
|
||||
|
||||
- Missing sections: [count]
|
||||
- Score: [X]/10
|
||||
|
||||
---
|
||||
|
||||
### Priority Issues
|
||||
|
||||
**High Priority (Fix Immediately):**
|
||||
|
||||
1. [Issue description and location]
|
||||
2. [...]
|
||||
|
||||
**Medium Priority (Fix Soon):**
|
||||
|
||||
1. [Issue description and location]
|
||||
2. [...]
|
||||
|
||||
**Low Priority (Nice to Have):**
|
||||
|
||||
1. [Issue description and location]
|
||||
2. [...]
|
||||
|
||||
---
|
||||
|
||||
### Recommended Actions
|
||||
|
||||
1. **Fix broken links:**
|
||||
- [Specific links to fix]
|
||||
|
||||
2. **Update version numbers:**
|
||||
- [Where to update]
|
||||
|
||||
3. **Standardize terminology:**
|
||||
- Use "[term]" instead of "[variation]"
|
||||
|
||||
4. **Complete missing sections:**
|
||||
- Add troubleshooting to README.md
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [x] Auto-fixed linting issues (markdownlint + prettier)
|
||||
- [ ] Review and fix high-priority semantic issues
|
||||
- [ ] Fix medium-priority issues (links, terminology, versions)
|
||||
- [ ] Consider low-priority improvements
|
||||
- [ ] Commit auto-fixes: `git commit -m "docs: Auto-fix linting issues (markdownlint + prettier)"`
|
||||
- [ ] Re-run QA to verify: `/ck:doc-review/qa`
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Auto-Fix Behavior
|
||||
|
||||
- **Automatic:** Linting tools run automatically on every QA check
|
||||
- **Non-destructive:** Only formatting and style issues are auto-fixed
|
||||
- **Semantic issues:** Links, terminology, versions require manual review
|
||||
- **Git-aware:** Shows diff of changes made
|
||||
|
||||
### Tool Requirements
|
||||
|
||||
- **markdownlint-cli:** Auto-fixes MD032, MD034, MD036, MD040, MD059
|
||||
- **prettier:** Enforces consistent code formatting
|
||||
- Both tools are lightweight and zero-dependency
|
||||
|
||||
### Configuration
|
||||
|
||||
Tools use standard configurations:
|
||||
|
||||
- `.markdownlintrc` - Markdownlint rules (if present)
|
||||
- `.prettierrc` - Prettier rules (if present)
|
||||
- Falls back to defaults if no config found
|
||||
150
commands/quick.md
Normal file
150
commands/quick.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
|
||||
description: Quick documentation update - skip analysis, direct edits only
|
||||
allowed-tools: Read(*), Edit(*), Write(*), Bash(git:*)
|
||||
---
|
||||
|
||||
# Quick Documentation Update
|
||||
|
||||
**⚡ Lightweight Mode** - No analysis, no validation, just updates
|
||||
**Token Cost:** 400-600 tokens (vs 1.2-1.5K for full :core)
|
||||
**Execution Time:** < 30 seconds
|
||||
**Use Case:** Known, simple documentation updates
|
||||
|
||||
---
|
||||
|
||||
## Task
|
||||
|
||||
**Quick update for:** $ARGUMENTS
|
||||
|
||||
**Fast path:** Skip analysis → Update files → Done
|
||||
|
||||
---
|
||||
|
||||
## Files to Update
|
||||
|
||||
Based on $ARGUMENTS, update one or more:
|
||||
|
||||
- **README.md** - Features, installation, usage, configuration
|
||||
- **CLAUDE.md** - AI context, module documentation
|
||||
- **CHANGELOG.md** - Add new version entry
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Identify Target File
|
||||
|
||||
Based on $ARGUMENTS, determine which file to update:
|
||||
|
||||
- Feature/usage change → README.md
|
||||
- New module/component → CLAUDE.md
|
||||
- Release/version change → CHANGELOG.md
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Direct Edit (No Analysis)
|
||||
|
||||
Quickly update the target file without analysis:
|
||||
|
||||
**For README.md:**
|
||||
- Add/update feature description in Features section
|
||||
- Update Installation if dependencies changed
|
||||
- Add Usage example
|
||||
|
||||
**For CLAUDE.md:**
|
||||
- Add new module documentation
|
||||
- Update architecture notes if changed
|
||||
- Document new components
|
||||
|
||||
**For CHANGELOG.md:**
|
||||
- Add new version entry at top
|
||||
- Categorize: Added/Changed/Fixed
|
||||
- Include dates and file references
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Quick Validation
|
||||
|
||||
Only check what was actually changed:
|
||||
|
||||
- ✅ File exists and is readable
|
||||
- ✅ No syntax errors in edited sections
|
||||
- ✅ Basic formatting correct
|
||||
|
||||
Do NOT run full QA or linting.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Summary
|
||||
|
||||
Show what was changed:
|
||||
|
||||
- Files modified: [list]
|
||||
- Lines changed: [approximate count]
|
||||
- Execution time: [< 30 seconds]
|
||||
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
```bash
|
||||
/ck:doc-review:quick "added new feature X"
|
||||
# Updates README.md with new feature → Done (< 1K tokens)
|
||||
|
||||
/ck:doc-review:quick "new API endpoint"
|
||||
# Updates CLAUDE.md with endpoint docs → Done (< 1K tokens)
|
||||
|
||||
/ck:doc-review:quick "version 1.2.0 release"
|
||||
# Updates CHANGELOG.md with release notes → Done (< 1K tokens)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Quick Mode
|
||||
|
||||
✅ **Use quick mode when:**
|
||||
- Update is simple and straightforward
|
||||
- You know exactly what needs changing
|
||||
- No validation needed
|
||||
- Speed is priority over completeness
|
||||
|
||||
❌ **Don't use quick mode when:**
|
||||
- Update is complex or affects multiple files
|
||||
- Need comprehensive analysis first
|
||||
- Want full QA validation
|
||||
- Documentation has many interconnections
|
||||
|
||||
---
|
||||
|
||||
## When to Use Full Mode
|
||||
|
||||
For comprehensive updates with analysis and validation:
|
||||
|
||||
```bash
|
||||
# Full analysis before updating
|
||||
/ck:doc-review:analyze "feature"
|
||||
|
||||
# Full update with QA validation
|
||||
/ck:doc-review:core "feature"
|
||||
|
||||
# SDD artifact updates
|
||||
/ck:doc-review:sdd "phase"
|
||||
|
||||
# Quality assurance
|
||||
/ck:doc-review:qa
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Savings Comparison
|
||||
|
||||
| Task | Mode | Tokens | Time |
|
||||
|------|------|--------|------|
|
||||
| Add feature to README | quick | 400-600 | < 30s |
|
||||
| Add feature to README | core | 1.2-1.5K | 2-3s |
|
||||
| New module to CLAUDE | quick | 400-600 | < 30s |
|
||||
| New module to CLAUDE | core | 1.2-1.5K | 2-3s |
|
||||
| CHANGELOG entry | quick | 300-500 | < 20s |
|
||||
| CHANGELOG entry | core | 1.2-1.5K | 2-3s |
|
||||
|
||||
**Savings:** 60-70% tokens, 90%+ execution time reduction
|
||||
|
||||
326
commands/sdd.md
Normal file
326
commands/sdd.md
Normal file
@@ -0,0 +1,326 @@
|
||||
---
|
||||
|
||||
description: Update SDD artifacts (spec.md, plan.md, tasks.md, contracts)
|
||||
allowed-tools: Bash(find:*), Bash(git:*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
|
||||
---
|
||||
|
||||
# SDD Artifacts Update Command
|
||||
|
||||
## Context
|
||||
|
||||
- SDD files:
|
||||
!`find ./specs -name "spec.md" -o -name "plan.md" -o -name "tasks.md" | sort`
|
||||
- Recent changes:
|
||||
!`git diff --name-only HEAD~5..HEAD 2>/dev/null || echo "No recent commits"`
|
||||
|
||||
## Task
|
||||
|
||||
**Update SDD artifacts for:** $ARGUMENTS
|
||||
|
||||
SDD stands for Specification-Driven Development.
|
||||
|
||||
**Target files:**
|
||||
|
||||
- specs/\*/spec.md - Functional requirements
|
||||
- specs/\*/plan.md - Implementation plan
|
||||
- specs/\*/tasks.md - Task breakdown
|
||||
- specs/_/contracts/_.md - Design contracts
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Identify Relevant Spec Directory
|
||||
|
||||
Based on $ARGUMENTS, determine which spec directory to update:
|
||||
|
||||
- Extract feature number (e.g., "feature 005" → specs/005-\*)
|
||||
- Or identify by feature name
|
||||
- List matching directories found
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Update spec.md (Functional Requirements)
|
||||
|
||||
### Read Current spec.md
|
||||
|
||||
Read the relevant specs/\*/spec.md file.
|
||||
|
||||
### Update Requirements
|
||||
|
||||
**What to update:**
|
||||
|
||||
1. **Mark Completed Requirements:**
|
||||
- Find requirements (FR-\*) that are now implemented
|
||||
- Change status markers:
|
||||
- [ ] → [x] for completed
|
||||
- Add ✅ emoji if used in doc
|
||||
|
||||
2. **Add New Requirements (if discovered during implementation):**
|
||||
|
||||
````markdown
|
||||
### FR-[N]: [Requirement Title]
|
||||
|
||||
**Priority:** [High/Medium/Low]
|
||||
**Status:** [Planned/In Progress/Completed]
|
||||
|
||||
**Description:**
|
||||
[What the requirement is]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
|
||||
**Implementation Notes:**
|
||||
[Details from actual implementation]
|
||||
````
|
||||
|
||||
3. **Update Requirement Details:**
|
||||
- Add implementation notes to existing requirements
|
||||
- Update acceptance criteria based on what was actually built
|
||||
- Note any deviations from original plan
|
||||
|
||||
### Make Updates
|
||||
|
||||
Apply changes using Edit tool.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Update plan.md (Implementation Plan)
|
||||
|
||||
### Read Current plan.md
|
||||
|
||||
Read the relevant specs/\*/plan.md file.
|
||||
|
||||
### Update Plan Status
|
||||
|
||||
**What to update:**
|
||||
|
||||
1. **Phase Completion:**
|
||||
|
||||
````markdown
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: [Name]
|
||||
|
||||
**Status:** ✅ Completed
|
||||
**Completion Date:** YYYY-MM-DD
|
||||
|
||||
**Implemented:**
|
||||
|
||||
- [What was built]
|
||||
- [What was built]
|
||||
|
||||
**Deviations:**
|
||||
|
||||
- [Any changes from original plan]
|
||||
````
|
||||
|
||||
2. **Architecture Decisions:**
|
||||
|
||||
````markdown
|
||||
### Architecture Decision: [Title]
|
||||
|
||||
**Decision:** [What was decided]
|
||||
**Rationale:** [Why this approach was chosen]
|
||||
**Alternatives Considered:** [Other options]
|
||||
**Implementation:** path/to/file.py:123
|
||||
**Trade-offs:**
|
||||
|
||||
- Pro: [Benefit]
|
||||
- Con: [Cost]
|
||||
````
|
||||
|
||||
3. **Design Patterns Used:**
|
||||
|
||||
````markdown
|
||||
### Design Pattern: [Pattern Name]
|
||||
|
||||
**Location:** path/to/implementation.py:123
|
||||
**Purpose:** [Why this pattern was used]
|
||||
**Implementation Details:** [How it's implemented]
|
||||
````
|
||||
|
||||
4. **Risk Updates:**
|
||||
- Mark mitigated risks as resolved
|
||||
- Add any new risks discovered
|
||||
- Update risk status
|
||||
|
||||
### Make Updates
|
||||
|
||||
Apply changes using Edit tool.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Update tasks.md (Task Breakdown)
|
||||
|
||||
### Read Current tasks.md
|
||||
|
||||
Read the relevant specs/\*/tasks.md file.
|
||||
|
||||
### Update Task Status
|
||||
|
||||
**What to update:**
|
||||
|
||||
1. **Mark Completed Tasks:**
|
||||
|
||||
````markdown
|
||||
- [x] Task name
|
||||
- **Status:** ✅ Completed
|
||||
- **Completion Date:** YYYY-MM-DD
|
||||
- **Implementation:** path/to/file.py:123
|
||||
- **Notes:** [Any lessons learned or important details]
|
||||
````
|
||||
|
||||
2. **Update In-Progress Tasks:**
|
||||
|
||||
````markdown
|
||||
- [ ] Task name
|
||||
- **Status:** 🔄 In Progress (60% complete)
|
||||
- **Current State:** [What's done, what's remaining]
|
||||
- **Blockers:** [Any issues]
|
||||
````
|
||||
|
||||
3. **Add New Tasks (if discovered):**
|
||||
|
||||
````markdown
|
||||
- [ ] New task discovered during implementation
|
||||
- **Priority:** High
|
||||
- **Dependency:** [Other tasks this depends on]
|
||||
- **Estimate:** [Time estimate]
|
||||
````
|
||||
|
||||
### Make Updates
|
||||
|
||||
Apply changes using Edit tool.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Update Design Contracts (if applicable)
|
||||
|
||||
### Find Contract Files
|
||||
|
||||
Look for specs/_/contracts/_.md files related to this feature.
|
||||
|
||||
### Update Contracts
|
||||
|
||||
**What to update:**
|
||||
|
||||
1. **API Contracts:**
|
||||
|
||||
````markdown
|
||||
## Endpoint: [Name]
|
||||
|
||||
**Method:** GET/POST/etc
|
||||
**Path:** /api/v1/resource
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"param": "value"
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Implementation:** path/to/handler.py:123
|
||||
|
||||
````
|
||||
|
||||
2. **Interface Contracts:**
|
||||
```markdown
|
||||
## Interface: [ClassName]
|
||||
|
||||
**Location:** path/to/file.py:123
|
||||
|
||||
**Methods:**
|
||||
- `method_name(param: Type) -> ReturnType`
|
||||
- Purpose: [What it does]
|
||||
- Example: [Usage example]
|
||||
````
|
||||
|
||||
3. **Data Schema Contracts:**
|
||||
- Update schema definitions to match actual implementation
|
||||
- Add examples with real data
|
||||
- Document any schema changes
|
||||
|
||||
### Make Updates
|
||||
|
||||
Apply changes using Edit tool for each contract file.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: SDD Consistency Validation
|
||||
|
||||
**Cross-check consistency:**
|
||||
|
||||
- [ ] spec.md requirements match implementation
|
||||
- [ ] plan.md phases align with completed tasks
|
||||
- [ ] tasks.md references correct file:line locations
|
||||
- [ ] Contracts match actual API/interface implementation
|
||||
- [ ] No orphaned requirements (in spec but not in plan/tasks)
|
||||
- [ ] All completed tasks have corresponding requirement markers
|
||||
|
||||
**If inconsistencies found:**
|
||||
|
||||
- Document them
|
||||
- Fix or note as deviations with explanation
|
||||
|
||||
---
|
||||
|
||||
## Output: Summary
|
||||
|
||||
### 📊 SDD Documentation Update Summary
|
||||
|
||||
**Scope:** $ARGUMENTS
|
||||
|
||||
**Spec Directory:** specs/[directory]
|
||||
|
||||
**Files Updated:**
|
||||
|
||||
| File | Updates Made | Lines Changed |
|
||||
| --------------- | ---------------------------------------- | ------------- |
|
||||
| spec.md | [FR-X completed, FR-Y updated] | ~[estimate] |
|
||||
| plan.md | [Phase X status, architecture decisions] | ~[estimate] |
|
||||
| tasks.md | [X tasks completed, Y added] | ~[estimate] |
|
||||
| contracts/\*.md | [Contracts updated] | ~[estimate] |
|
||||
|
||||
**Requirement Status:**
|
||||
|
||||
- Completed: [count] requirements
|
||||
- In Progress: [count] requirements
|
||||
- Remaining: [count] requirements
|
||||
|
||||
**Phase Status:**
|
||||
|
||||
- Completed phases: [list]
|
||||
- Current phase: [name] ([%] complete)
|
||||
- Remaining phases: [list]
|
||||
|
||||
**SDD Consistency:**
|
||||
|
||||
- [x] Requirements ↔ Implementation aligned
|
||||
- [x] Plan ↔ Tasks aligned
|
||||
- [x] Contracts ↔ Code aligned
|
||||
- [x] No orphaned requirements
|
||||
- [x] All references accurate
|
||||
|
||||
**Execution Time:** [X]s
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
Recommended actions:
|
||||
|
||||
- [ ] Review SDD updates: `git diff specs/`
|
||||
- [ ] Update core docs: `/ck:doc-review/core $ARGUMENTS`
|
||||
- [ ] Run QA validation: `/ck:doc-review/qa`
|
||||
- [ ] Commit SDD updates with message like: `docs(sdd): Update spec 005 for feature implementation`
|
||||
Reference in New Issue
Block a user