DavidROliverBA/.claude/skills/system-sync

/system-sync Skill

Sync systems and architecture data with external sources (CMDB, Confluence, ServiceNow, Jira).

When to Use This Skill

Use /system-sync when you need to:

• Sync system metadata from enterprise CMDB
• Sync architecture documentation from Confluence
• Sync ADRs from organization governance systems
• Synchronize with multiple data sources
• Create single source of truth for architecture data
• Validate vault data against authoritative sources
• Detect drift between local and remote definitions

Usage

/system-sync <source> [filter] [options]

Parameters

| Parameter | Description | Required | |-----------|-------------|----------| | source | Data source (cmdb, confluence, servicenow, jira, all) | Yes | | filter | Filter by type, tag, or search term | Optional | | --mode | Sync mode (fetch, validate, merge, publish) | Optional | | --direction | Direction (pull, push, bidirectional) | Optional | | --dry-run | Preview changes without applying | Optional |

Supported Sources

1. CMDB (Configuration Management Database)

Typical source: ServiceNow CMDB, BMC CMDB, or custom CMDB

What syncs:

• Systems (name, type, owner, environment)
• System dependencies (connectsTo relationships)
• System metadata (IP addresses, hosts, ports)
• Deployment information (which account/region)
• Operational contacts (on-call, support)

Examples:

/system-sync cmdb --filter "type:Application"          # Sync all applications
/system-sync cmdb --filter "environment:production"    # Production systems only
/system-sync cmdb --dry-run                            # Preview changes

2. Confluence

Typical source: YourOrg Enterprise Confluence (wiki documentation)

What syncs:

• Architecture documentation (HLD, LLD, ADRs)
• System catalogs and inventories
• Integration documentation
• Governance policies and guardrails
• Strategic roadmaps
• Decision records

Examples:

/system-sync confluence --filter "space:ARCHITECTURE"  # All architecture docs
/system-sync confluence --filter "label:adr"           # All ADRs
/system-sync confluence --dry-run

3. ServiceNow

Typical source: YourOrg Service Management (change, incident, CMDB)

What syncs:

• Service mappings (services and supporting CIs)
• Change calendars (what's changing when)
• Incident history (what systems failed when)
• Change management data (deployments, cutover plans)
• SLA definitions

Examples:

/system-sync servicenow --filter "service:DataPlatform"        # DataPlatform service and dependents
/system-sync servicenow --mode validate                # Check for conflicts

4. Jira

Typical source: YourOrg Engineering Jira (projects, issues, roadmaps)

What syncs:

• Project metadata (status, team, roadmap)
• Epic/Feature definitions
• ADRs as Jira records
• Technology decisions from issues
• Release planning

Examples:

/system-sync jira --filter "project:MyDataIntegration"            # MyDataIntegration project info
/system-sync jira --filter "type:ADR"                  # ADRs in Jira

Sync Modes

1. Fetch (Pull from Source)

/system-sync cmdb --mode fetch

What happens:

1. Queries source system
2. Reads all matching records
3. Creates/updates local notes
4. Marks records with source: cmdb, lastSynced: <timestamp>
5. Preserves local edits (non-authoritative fields)

Local fields preserved:

• Analysis and commentary
• Architecture context
• Decision rationale
• Local relationships

Remote fields updated:

• System name, type, owner
• Dependencies and relationships
• Metadata (IP addresses, hosts)
• Contact information

2. Validate (Check for Conflicts)

/system-sync cmdb --mode validate

What happens:

1. Queries source system
2. Compares with local notes
3. Reports discrepancies:
   • System exists locally but not in CMDB
   • System exists in CMDB but not locally
   • Metadata differs (owner, criticality, etc.)
   • Dependencies differ
4. Generates validation report

Output example:

Validation Results: CMDB
────────────────────────────────
Total Systems: 25
✓ In Sync: 22
⚠ Out of Sync: 2
✗ Inconsistent: 1

Out of Sync:
- SAP S/4HANA
  • Local: criticality=critical
  • CMDB: criticality=high
  • Action: Update local or CMDB

Inconsistent:
- DataPlatform
  • Local: owner=John Smith
  • CMDB: owner=Data Platform Team
  • Action: Investigate

3. Merge (Bidirectional Reconciliation)

/system-sync cmdb --mode merge --dry-run

What happens:

1. Compares local and remote
2. Merges data intelligently:
   • Takes more recent data
   • Preserves local analysis/context
   • Updates relationships
3. Resolves conflicts interactively
4. Creates merged records

Conflict resolution:

• If local and remote both changed: User chooses which to keep
• If only local changed: Keeps local
• If only remote changed: Takes remote
• If both unchanged: No action needed

4. Publish (Push to Source)

/system-sync confluence --mode publish

What happens:

1. Reads local notes (System, Integration, Architecture)
2. Converts to target format (Confluence pages, Jira issues, etc.)
3. Creates/updates records in target system
4. Tracks publication in publishedUrl field

Publication options:

• Create new pages/records (if not published before)
• Update existing (if already published)
• Archive deprecated records

Workflow

Phase 1: Configure Source

User specifies:

1. Source system

   • CMDB, Confluence, ServiceNow, or Jira
   • Which instance/environment
   • Authentication credentials (OAuth token, API key)

2. Sync filter

   • Which records to sync (type, tag, search)
   • Optionally: Which fields to sync

3. Sync mode

   • Fetch (pull), Validate (check), Merge (reconcile), Publish (push)

4. Dry-run?

   • Preview changes without applying

Phase 2: Execute Sync

The skill:

1. Connects to source

2. Queries records matching filter

3. For each record:

   • Find matching local note (by ID, name, or fuzzy match)
   • Apply sync mode (fetch/validate/merge/publish)
   • Track changes

4. Creates sync report showing:

   • Records processed
   • Records created
   • Records updated
   • Records with conflicts
   • Errors (if any)

Phase 3: Review and Confirm

If dry-run:

1. Show preview of all changes
2. User confirms or cancels
3. If confirmed, apply changes for real

If not dry-run:

1. Apply changes immediately
2. Show summary report

Phase 4: Post-Sync Actions

Optionally:

1. Create summary notes for new systems
2. Generate diagrams for new architectures
3. Trigger validation queries (e.g., find orphaned notes)
4. Notify stakeholders of sync results

Examples

Example 1: Fetch CMDB Systems

/system-sync cmdb --filter "type:Application" --dry-run

Preview Output:

Sync Mode: Fetch (Pull from CMDB)
Filter: type="Application"
Dry-Run: Yes (preview only)

Proposed Changes:
────────────────
Create (New):
  ✓ ServiceNow (Service Management)
  ✓ Splunk (Log Management)

Update (Existing):
  ✓ SAP S/4HANA (update criticality: high → critical)
  ✓ DataPlatform (update owner, contacts)
  ✓ Snowflake (update deployment region)

Total: 5 records affected

User confirms → Changes applied:

• Creates 2 new System notes
• Updates 3 existing System notes
• All marked with source: cmdb, lastSynced: 2026-01-14T14:32:00Z

Example 2: Validate Confluence Architecture Docs

/system-sync confluence --filter "label:architecture" --mode validate

Output:

Validation Mode: Confluence Architecture Documentation
Filter: label="architecture"

Results:
────────
✓ In Sync: 8 ADRs
⚠ Out of Sync: 2 pages
✗ Missing: 1 page not in local vault

Out of Sync Details:
- "ADR - API Gateway Selection"
  • Confluence version: 5 (2026-01-10)
  • Local version: 4 (2026-01-08)
  • Recommendation: Fetch latest from Confluence

- "Architecture - Data Integration Platform"
  • Confluence: Minor edits only
  • Local: Significant additions (new scenarios)
  • Recommendation: Publish local version to Confluence

Missing from Vault:
- "Page - Authorization Strategy Review"
  • Last modified: 2025-12-15
  • Status: Active
  • Recommendation: Fetch into vault

Example 3: Publish Local ADRs to Confluence

/system-sync confluence --filter "type:Adr" --mode publish --direction push

Output:

Publication Mode: Local → Confluence
Filter: type="Adr"

Proposed Actions:
─────────────────
Create New Pages (Not Published):
  ✓ ADR - Snowflake as Analytics Warehouse
  ✓ ADR - Looker vs Tableau Selection
  ✓ ADR - Real-time Streaming Architecture

Update Existing Pages (Already Published):
  ✓ ADR - API Gateway Selection (version 5 → 6)
  ✓ ADR - SAP to AWS Connectivity (version 3 → 4)

Archive Deprecated (in Confluence, mark as deprecated):
  ✓ ADR - Tableau BI Platform (superseded by Looker)

Total: 10 pages affected

User confirms → Published to Confluence

Example 4: Bidirectional Merge with CMDB

/system-sync cmdb --mode merge

Intelligent merge:

• CMDB has updated system criticality → Update local
• Local has updated system owner in Confluence → Keep local
• Both have different SLA definitions → User resolves conflict

Result:

• Authoritative system metadata from CMDB
• Enriched with local analysis and context
• Conflict-free, single source of truth

Sync Report Structure

Each sync generates a detailed report:

Report Section 1: Summary

Sync Summary Report
═══════════════════════════════════════════════════════════
Source: CMDB (Configuration Management Database)
Mode: Fetch (Pull)
Filter: type="Application", environment="production"
Dry-Run: No (changes applied)
Timestamp: 2026-01-14T14:32:00Z

Records Processed:     25
Records Created:        3
Records Updated:        8
Records Unchanged:     14
Records with Errors:    0
─────────────────────────────────────────────────────────
Total Time: 3.2 seconds
Status: ✓ Success

Report Section 2: Created Records

New Records Created:
───────────────────
1. System - ServiceNow
   • Name: ServiceNow Service Management
   • Type: Platform
   • Owner: IT Service Management
   • Criticality: Medium
   • Status: Active

2. System - Splunk
   • Name: Splunk Log Management
   • Type: Platform
   • Owner: Operations & Engineering
   • Criticality: High
   • Status: Active

Report Section 3: Updated Records

Records Updated:
────────────────
1. System - SAP S/4HANA
   Changes:
   • criticality: high → critical
   • owner: "IT Applications" → "Finance IT"
   • dataClassification: internal → confidential

2. System - DataPlatform
   Changes:
   • contacts (support): [John, Sarah] → [John, Sarah, Mike]
   • status: active → active (no change)

Report Section 4: Errors/Conflicts

Sync Errors (0):
────────────────
None

Unresolved Conflicts (0):
─────────────────────────
None

Warnings (1):
─────────────
1. System "Cloud Foundry" found in CMDB but no matching local note
   Recommendation: Create new System note or add to exclusion filter

Sync Metadata

Records synced from external sources include:

# Sync Source Fields
source: cmdb | confluence | servicenow | jira
sourceId: "<unique-id-in-source>"
sourceUrl: "<url-to-source-record>"
sourceVersion: <version-number>
lastSynced: <ISO-timestamp>
syncMode: fetch | merge

# Authority
readOnly: false                    # Can local edits be synced back?
authoritative: <field-list>       # Which fields come from source

Advanced Options

Selective Field Sync

/system-sync cmdb --fields "owner,criticality,contacts" --dry-run

Only sync specific fields, preserve local edits to other fields.

Conflict Resolution Strategy

/system-sync cmdb --conflicts "ask|remote|local|newer|merge"

• ask - Prompt user for each conflict (default)
• remote - Always take source value
• local - Always keep local value
• newer - Take whichever was updated most recently
• merge - Intelligently merge (combine lists, keep both)

Schedule Automatic Syncs

/system-sync cmdb --schedule "daily at 02:00" --store

Configure recurring sync (stored in vault settings).

Exclude Records

/system-sync cmdb --exclude "status:deprecated,tag:archived"

Skip records matching filter.

Integration with Other Skills

The /system-sync skill works with:

• /system - Create/update System notes from synced data
• /integration - Update Integration notes with synced dependencies
• /diagram - Regenerate diagrams after sync
• /vault-maintenance - Detect orphaned notes after sync

Error Handling

Common sync errors and solutions:

| Error | Cause | Solution | |-------|-------|----------| | Authentication failed | Wrong credentials | Check API key/token in settings | | No matching records | Filter too restrictive | Broaden filter or check source data | | Cannot match records | Naming differs | Use source ID for matching, or manual map | | Field not found | Field doesn't exist in source | Update field mapping config | | Connection timeout | Network/firewall issue | Check network, retry, or use proxy |

Sync Best Practices

1. Always dry-run first - Preview changes before applying
2. Sync during maintenance window - Minimize user impact
3. Review sync reports - Check for unexpected changes
4. Version control - Commit before/after syncs to git
5. Monitor quality - Run validation sync periodically
6. Document mappings - Keep field mappings documented
7. Notify stakeholders - Let teams know when data synced

Sync Validation Queries

After syncing, run these queries to verify:

// Find systems with mismatched owners
TABLE owner, cmdbOwner
FROM ""
WHERE type = "System" AND owner != cmdbOwner

// Find orphaned local systems (not in CMDB)
TABLE source, sourceId
FROM ""
WHERE type = "System" AND source != "cmdb"

Next Steps

After syncing:

1. Review sync report for any surprises
2. Run validation queries to check consistency
3. Update diagrams if topology changed (/diagram --refresh)
4. Notify stakeholders of sync completion
5. Schedule next sync cycle

Configuration

Sync sources configured in .claude/sync-config.yaml:

cmdb:
  url: "https://cmdb.yourorg.internal/api"
  auth: oauth2
  updateFrequency: daily

confluence:
  url: "https://confluence.yourorg.internal"
  space: ARCHITECTURE
  auth: oauth2

servicenow:
  instance: "yourorg"
  auth: oauth2

jira:
  url: "https://jira.yourorg.internal"
  projects: ["MyDataIntegration", "ModernizationProject", "DataPlatform"]
  auth: oauth2

---

Invoke with: /system-sync <source>

Example: /system-sync cmdb --filter "environment:production" --dry-run → Preview sync of production systems