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:

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

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

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

# 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