432 lines
12 KiB
Markdown
432 lines
12 KiB
Markdown
---
|
|
name: project-docs-sync
|
|
description: Automatically synchronize project documentation when major changes occur (new tech, architecture changes, requirements shifts). Detects significant updates and propagates changes across TECH-STACK.md, ARCHITECTURE.md, and SPECIFICATIONS.md.
|
|
---
|
|
|
|
# Project Documentation Sync Skill
|
|
|
|
**Purpose**: Keep project documentation consistent without manual syncing overhead.
|
|
|
|
**Trigger**: Auto-invoked by PostToolUse hook when files in `project-management/` are edited.
|
|
|
|
---
|
|
|
|
## Decision Logic: Should We Sync?
|
|
|
|
```python
|
|
def should_sync(change: dict) -> tuple[bool, str]:
|
|
"""Conservative sync decision - only on big changes."""
|
|
|
|
# Track last sync state
|
|
last_sync = load_last_sync() # from .meta/last-sync.json
|
|
|
|
significant_changes = {
|
|
# Technology changes
|
|
"added_technology": True, # New language, framework, library
|
|
"removed_technology": True, # Deprecated/removed tech
|
|
"upgraded_major_version": True, # React 17 → 18, Python 3.10 → 3.11
|
|
|
|
# Architecture changes
|
|
"added_service": True, # New microservice, component
|
|
"removed_service": True, # Deprecated service
|
|
"changed_data_flow": True, # New integration pattern
|
|
"added_integration": True, # New third-party API
|
|
|
|
# Requirements changes
|
|
"new_security_requirement": True,
|
|
"new_performance_requirement": True,
|
|
"changed_api_contract": True,
|
|
"added_compliance_need": True,
|
|
}
|
|
|
|
# Skip minor changes
|
|
minor_changes = {
|
|
"typo_fix": False,
|
|
"formatting": False,
|
|
"comment_update": False,
|
|
"example_clarification": False,
|
|
}
|
|
|
|
change_type = classify_change(change, last_sync)
|
|
return significant_changes.get(change_type, False), change_type
|
|
```
|
|
|
|
---
|
|
|
|
## What Gets Synced (Conservative Strategy)
|
|
|
|
### 1. TECH-STACK.md Changed → Update ARCHITECTURE.md
|
|
|
|
**Triggers:**
|
|
- Added new language/framework (e.g., added Redis)
|
|
- Removed technology (e.g., removed MongoDB)
|
|
- Major version upgrade (e.g., React 17 → 18)
|
|
|
|
**Sync Actions:**
|
|
```markdown
|
|
TECH-STACK.md shows:
|
|
+ Redis 7.x (added for caching)
|
|
|
|
→ Update ARCHITECTURE.md:
|
|
- Add Redis component to architecture diagram
|
|
- Add caching layer to data flow
|
|
- Document Redis connection pattern
|
|
```
|
|
|
|
**Example Output:**
|
|
```
|
|
✓ Synced TECH-STACK.md → ARCHITECTURE.md
|
|
- Added: Redis caching layer
|
|
- Updated: Data flow diagram (added cache lookup)
|
|
- Reason: New technology requires architectural integration
|
|
```
|
|
|
|
---
|
|
|
|
### 2. ARCHITECTURE.md Changed → Update SPECIFICATIONS.md
|
|
|
|
**Triggers:**
|
|
- New service/component added
|
|
- API gateway pattern introduced
|
|
- Data model changed
|
|
- Integration pattern modified
|
|
|
|
**Sync Actions:**
|
|
```markdown
|
|
ARCHITECTURE.md shows:
|
|
+ API Gateway (Kong) added between clients and services
|
|
|
|
→ Update SPECIFICATIONS.md:
|
|
- Add API Gateway endpoints
|
|
- Update authentication flow
|
|
- Add rate limiting specs
|
|
- Update API contract examples
|
|
```
|
|
|
|
**Example Output:**
|
|
```
|
|
✓ Synced ARCHITECTURE.md → SPECIFICATIONS.md
|
|
- Added: API Gateway endpoint specs
|
|
- Updated: Authentication flow (now via gateway)
|
|
- Reason: Architectural change affects API contracts
|
|
```
|
|
|
|
---
|
|
|
|
### 3. PROJECT-OVERVIEW.md Changed → Validate Consistency
|
|
|
|
**Triggers:**
|
|
- Project scope changed
|
|
- New requirement category added
|
|
- Compliance requirement added
|
|
- Target users changed
|
|
|
|
**Sync Actions:**
|
|
```markdown
|
|
PROJECT-OVERVIEW.md shows:
|
|
+ Compliance: GDPR data privacy required
|
|
|
|
→ Validate across all docs:
|
|
- Check TECH-STACK.md has encryption libraries
|
|
- Check ARCHITECTURE.md has data privacy layer
|
|
- Check SPECIFICATIONS.md has GDPR endpoints (data export, deletion)
|
|
- Flag missing pieces
|
|
```
|
|
|
|
**Example Output:**
|
|
```
|
|
⚠ Validation: PROJECT-OVERVIEW.md → ALL DOCS
|
|
- Missing in TECH-STACK.md: No encryption library listed
|
|
- Missing in SPECIFICATIONS.md: No GDPR data export endpoint
|
|
- Recommendation: Add encryption lib + GDPR API specs
|
|
```
|
|
|
|
---
|
|
|
|
## Change Detection Algorithm
|
|
|
|
```python
|
|
def classify_change(file_path: str, diff: str, last_sync: dict) -> str:
|
|
"""Classify change significance using diff analysis."""
|
|
|
|
# Parse diff
|
|
added_lines = [line for line in diff.split('\n') if line.startswith('+')]
|
|
removed_lines = [line for line in diff.split('\n') if line.startswith('-')]
|
|
|
|
# Check for technology changes
|
|
tech_keywords = ['framework', 'library', 'language', 'database', 'cache']
|
|
if any(kw in line.lower() for line in added_lines for kw in tech_keywords):
|
|
if any(removed_lines): # Replacement
|
|
return "upgraded_major_version"
|
|
return "added_technology"
|
|
|
|
# Check for architecture changes
|
|
arch_keywords = ['service', 'component', 'layer', 'gateway', 'microservice']
|
|
if any(kw in line.lower() for line in added_lines for kw in arch_keywords):
|
|
return "added_service"
|
|
|
|
# Check for requirement changes
|
|
req_keywords = ['security', 'performance', 'compliance', 'GDPR', 'HIPAA']
|
|
if any(kw in line.lower() for line in added_lines for kw in req_keywords):
|
|
return "new_security_requirement"
|
|
|
|
# Check for API contract changes
|
|
if 'endpoint' in diff.lower() or 'route' in diff.lower():
|
|
return "changed_api_contract"
|
|
|
|
# Default: minor change (skip sync)
|
|
if len(added_lines) < 3 and not removed_lines:
|
|
return "typo_fix"
|
|
|
|
return "unknown_change"
|
|
```
|
|
|
|
---
|
|
|
|
## Sync State Tracking
|
|
|
|
**Storage**: `.meta/last-sync.json`
|
|
|
|
```json
|
|
{
|
|
"last_sync_timestamp": "2025-10-30T14:30:00Z",
|
|
"synced_files": {
|
|
"project-management/TECH-STACK.md": {
|
|
"hash": "abc123",
|
|
"last_modified": "2025-10-30T14:00:00Z",
|
|
"change_type": "added_technology"
|
|
},
|
|
"project-management/ARCHITECTURE.md": {
|
|
"hash": "def456",
|
|
"last_modified": "2025-10-30T14:30:00Z",
|
|
"synced_from": "TECH-STACK.md"
|
|
}
|
|
},
|
|
"pending_syncs": []
|
|
}
|
|
```
|
|
|
|
**Update Logic**:
|
|
1. After Write/Edit to `project-management/*.md`
|
|
2. Calculate file hash (md5 of content)
|
|
3. Compare with last sync state
|
|
4. If different + significant change → Trigger sync
|
|
5. Update `.meta/last-sync.json`
|
|
|
|
---
|
|
|
|
## Sync Execution Flow
|
|
|
|
```
|
|
PostToolUse Hook Fires
|
|
↓
|
|
File edited: project-management/TECH-STACK.md
|
|
↓
|
|
Load .meta/last-sync.json
|
|
↓
|
|
Calculate diff from last sync
|
|
↓
|
|
Classify change: "added_technology" (Redis)
|
|
↓
|
|
Decision: should_sync() → TRUE
|
|
↓
|
|
┌────────────────────────────────────┐
|
|
│ Sync: TECH-STACK → ARCHITECTURE │
|
|
│ - Read TECH-STACK.md additions │
|
|
│ - Identify: Redis 7.x (cache) │
|
|
│ - Update ARCHITECTURE.md: │
|
|
│ + Add Redis component │
|
|
│ + Update data flow │
|
|
└────────────────────────────────────┘
|
|
↓
|
|
Write updated ARCHITECTURE.md
|
|
↓
|
|
Update .meta/last-sync.json
|
|
↓
|
|
Log sync action
|
|
↓
|
|
Output brief sync report
|
|
```
|
|
|
|
---
|
|
|
|
## Sync Report Format
|
|
|
|
```markdown
|
|
## Documentation Sync Report
|
|
|
|
**Trigger**: TECH-STACK.md modified (added Redis)
|
|
**Timestamp**: 2025-10-30T14:30:00Z
|
|
|
|
---
|
|
|
|
### Changes Detected: 1
|
|
|
|
1. **[SIGNIFICANT] Added technology: Redis 7.x**
|
|
- **Source**: project-management/TECH-STACK.md:45
|
|
- **Purpose**: Caching layer for API responses
|
|
|
|
---
|
|
|
|
### Syncs Applied: 2
|
|
|
|
1. **TECH-STACK.md → ARCHITECTURE.md**
|
|
- ✓ Added: Redis component to architecture diagram
|
|
- ✓ Updated: Data flow (added cache lookup step)
|
|
- ✓ File: project-management/ARCHITECTURE.md:120-135
|
|
|
|
2. **TECH-STACK.md → SPECIFICATIONS.md**
|
|
- ✓ Added: Cache invalidation API endpoint
|
|
- ✓ Updated: Response time expectations (now <100ms with cache)
|
|
- ✓ File: project-management/SPECIFICATIONS.md:78-82
|
|
|
|
---
|
|
|
|
### Validation Checks: 2
|
|
|
|
✓ TECH-STACK.md consistency: OK
|
|
✓ ARCHITECTURE.md alignment: OK
|
|
|
|
---
|
|
|
|
**Result**: Documentation synchronized successfully.
|
|
**Next Action**: Review changes in next commit.
|
|
```
|
|
|
|
---
|
|
|
|
## Integration with PostToolUse Hook
|
|
|
|
**Hook Location**: `.claude/hooks/post_tool_use_format.py`
|
|
|
|
**Trigger Condition**:
|
|
```python
|
|
def should_trigger_docs_sync(file_path: str, tool_name: str) -> bool:
|
|
"""Only trigger on project-management doc edits."""
|
|
|
|
if tool_name not in ["Write", "Edit"]:
|
|
return False
|
|
|
|
project_docs = [
|
|
"project-management/TECH-STACK.md",
|
|
"project-management/ARCHITECTURE.md",
|
|
"project-management/PROJECT-OVERVIEW.md",
|
|
"project-management/SPECIFICATIONS.md",
|
|
]
|
|
|
|
return any(doc in file_path for doc in project_docs)
|
|
```
|
|
|
|
**Invocation**:
|
|
```python
|
|
# In PostToolUse hook
|
|
if should_trigger_docs_sync(file_path, tool_name):
|
|
# Load skill
|
|
skill_result = invoke_skill("project-docs-sync", {
|
|
"file_path": file_path,
|
|
"change_type": classify_change(file_path, diff),
|
|
"last_sync_state": load_last_sync()
|
|
})
|
|
|
|
# Log sync action
|
|
log_sync_action(skill_result)
|
|
```
|
|
|
|
---
|
|
|
|
## Sync Strategies by File Type
|
|
|
|
### TECH-STACK.md → ARCHITECTURE.md
|
|
**What to sync:**
|
|
- New databases → Add data layer component
|
|
- New frameworks → Add to tech stack diagram
|
|
- New APIs → Add integration points
|
|
- Version upgrades → Update compatibility notes
|
|
|
|
### ARCHITECTURE.md → SPECIFICATIONS.md
|
|
**What to sync:**
|
|
- New services → Add service endpoints
|
|
- New integrations → Add API contracts
|
|
- Data model changes → Update request/response schemas
|
|
- Security layers → Add authentication specs
|
|
|
|
### PROJECT-OVERVIEW.md → ALL DOCS
|
|
**What to validate:**
|
|
- Compliance requirements → Check encryption in TECH-STACK
|
|
- Performance goals → Check caching in ARCHITECTURE
|
|
- Target users → Check API design in SPECIFICATIONS
|
|
- Scope changes → Validate alignment across all docs
|
|
|
|
---
|
|
|
|
## Conservative Sync Rules
|
|
|
|
**DO Sync When:**
|
|
- ✅ New technology added (database, framework, library)
|
|
- ✅ Service/component added or removed
|
|
- ✅ API contract changed (new endpoint, schema change)
|
|
- ✅ Compliance requirement added (GDPR, HIPAA)
|
|
- ✅ Major version upgrade (breaking changes possible)
|
|
|
|
**DO NOT Sync When:**
|
|
- ❌ Typo fixes (1-2 character changes)
|
|
- ❌ Formatting changes (whitespace, markdown)
|
|
- ❌ Comment/example clarifications
|
|
- ❌ Documentation of existing features (no new info)
|
|
- ❌ Minor version bumps (patch releases)
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
**If sync fails:**
|
|
1. Log error to `.meta/sync-errors.log`
|
|
2. Add to pending syncs in `.meta/last-sync.json`
|
|
3. Report to user with clear action items
|
|
4. Do NOT block the write operation (non-blocking)
|
|
|
|
**Example Error Report:**
|
|
```
|
|
⚠ Documentation Sync Failed
|
|
|
|
**File**: project-management/TECH-STACK.md
|
|
**Error**: Could not parse ARCHITECTURE.md (syntax error)
|
|
**Action Required**:
|
|
1. Fix ARCHITECTURE.md syntax error (line 45)
|
|
2. Re-run: /lazy docs-sync
|
|
|
|
**Pending Syncs**: 1 (tracked in .meta/last-sync.json)
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
```bash
|
|
# Disable auto-sync (manual /lazy docs-sync only)
|
|
export LAZYDEV_DISABLE_DOCS_SYNC=1
|
|
|
|
# Sync everything (even minor changes)
|
|
export LAZYDEV_DOCS_SYNC_AGGRESSIVE=1
|
|
|
|
# Sync specific files only
|
|
export LAZYDEV_DOCS_SYNC_FILES="TECH-STACK.md,ARCHITECTURE.md"
|
|
```
|
|
|
|
---
|
|
|
|
## What This Skill Does NOT Do
|
|
|
|
❌ Sync code files (only project-management docs)
|
|
❌ Generate docs from scratch (use `/lazy docs`)
|
|
❌ Fix documentation errors (use `/lazy fix`)
|
|
❌ Create missing docs (use `/lazy plan`)
|
|
|
|
✅ **DOES**: Automatically propagate significant changes across project documentation with conservative triggers.
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Non-blocking**: Syncs in background, logs errors
|
|
**Speed**: <2 seconds for typical sync
|