DavidROliverBA/ArchitectKB / .claude/skills/system-sync
system-sync
Verified/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:
- Queries source system
- Reads all matching records
- Creates/updates local notes
- Marks records with
source: cmdb,lastSynced: <timestamp> - 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:
- Queries source system
- Compares with local notes
- Reports discrepancies:
- System exists locally but not in CMDB
- System exists in CMDB but not locally
- Metadata differs (owner, criticality, etc.)
- Dependencies differ
- 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:
- Compares local and remote
- Merges data intelligently:
- Takes more recent data
- Preserves local analysis/context
- Updates relationships
- Resolves conflicts interactively
- 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:
- Reads local notes (System, Integration, Architecture)
- Converts to target format (Confluence pages, Jira issues, etc.)
- Creates/updates records in target system
- Tracks publication in
publishedUrlfield
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:
-
Source system
- CMDB, Confluence, ServiceNow, or Jira
- Which instance/environment
- Authentication credentials (OAuth token, API key)
-
Sync filter
- Which records to sync (type, tag, search)
- Optionally: Which fields to sync
-
Sync mode
- Fetch (pull), Validate (check), Merge (reconcile), Publish (push)
-
Dry-run?
- Preview changes without applying
Phase 2: Execute Sync
The skill:
-
Connects to source
-
Queries records matching filter
-
For each record:
- Find matching local note (by ID, name, or fuzzy match)
- Apply sync mode (fetch/validate/merge/publish)
- Track changes
-
Creates sync report showing:
- Records processed
- Records created
- Records updated
- Records with conflicts
- Errors (if any)
Phase 3: Review and Confirm
If dry-run:
- Show preview of all changes
- User confirms or cancels
- If confirmed, apply changes for real
If not dry-run:
- Apply changes immediately
- Show summary report
Phase 4: Post-Sync Actions
Optionally:
- Create summary notes for new systems
- Generate diagrams for new architectures
- Trigger validation queries (e.g., find orphaned notes)
- 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 valuelocal- Always keep local valuenewer- Take whichever was updated most recentlymerge- 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
- Always dry-run first - Preview changes before applying
- Sync during maintenance window - Minimize user impact
- Review sync reports - Check for unexpected changes
- Version control - Commit before/after syncs to git
- Monitor quality - Run validation sync periodically
- Document mappings - Keep field mappings documented
- 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:
- Review sync report for any surprises
- Run validation queries to check consistency
- Update diagrams if topology changed (
/diagram --refresh) - Notify stakeholders of sync completion
- 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |