majiayu000 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?
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:
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:
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:
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
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
{
"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:
- After Write/Edit to
project-management/*.md - Calculate file hash (md5 of content)
- Compare with last sync state
- If different + significant change → Trigger sync
- 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
## 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:
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:
# 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:
- Log error to
.meta/sync-errors.log - Add to pending syncs in
.meta/last-sync.json - Report to user with clear action items
- 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
# 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