Syncing Submodules

Intelligent Submodule Sync System

This skill provides a sophisticated framework for syncing components from git submodules while ensuring consistency, avoiding duplicates, and maintaining quality.

Core Principles

1. No Duplicates - Same concept should exist only once
2. No Near-Duplicates - Similar concepts should be merged
3. Quality Over Quantity - Better to have fewer excellent components than many mediocre ones
4. Semantic Analysis - Compare meaning, not just names
5. Synthesis Over Copying - Create superior merged versions

Phase 1: Deep Discovery

1.1 Scan All Submodules

# Update submodules
git submodule update --remote --merge

# Create inventory
for submodule in submodules/*/; do
  echo "=== $submodule ==="
  find "$submodule" -name "SKILL.md" -o -name "*.md" -path "*/commands/*" -o -name "*.md" -path "*/agents/*"
done

1.2 Extract Component Metadata

For EACH discovered component, extract:

component:
  name: "component-name"
  type: "skill|agent|command|hook"
  source: "submodule-name"
  path: "full/path/to/file"

  # Deep analysis fields
  primary_purpose: "One sentence describing main function"
  keywords: ["keyword1", "keyword2", "keyword3"]
  capabilities: ["capability1", "capability2"]
  target_audience: "who uses this"
  domain: "core|engineering|data|devops|design|product|github"

Phase 2: Semantic Similarity Analysis

2.1 Similarity Detection Matrix

For each pair of components (existing + new), calculate similarity:

2.2 Similarity Thresholds

2.3 Semantic Comparison Checklist

When comparing two similar components:

## Comparison: [Component A] vs [Component B]

### Purpose Analysis
- A's purpose: ___
- B's purpose: ___
- Overlap: ___% | Distinct: ___%

### Content Comparison
| Aspect | Component A | Component B | Better |
|--------|-------------|-------------|--------|
| Completeness | 1-10 | 1-10 | A/B |
| Clarity | 1-10 | 1-10 | A/B |
| Examples | count | count | A/B |
| Edge cases | count | count | A/B |
| Actionability | 1-10 | 1-10 | A/B |

### Unique Features
- Only in A: ___
- Only in B: ___

### Decision: [KEEP_A | KEEP_B | MERGE | KEEP_BOTH]
### Rationale: ___

Phase 3: Quality Scoring

3.1 Component Quality Rubric

Score each component 0-100:

3.2 Quality Thresholds

Phase 4: Conflict Resolution

4.1 Same Concept, Different Names

Example: "verification" vs "validation" vs "checking-work"

Resolution Process:

1. Identify all variants
2. Analyze each for unique value
3. Choose canonical name (most intuitive)
4. Merge all content into canonical
5. Ensure description covers ALL trigger phrases

4.2 Same Name, Different Purposes

Example: Two "debug" commands doing different things

Resolution Process:

1. Determine which aligns with ltk's existing conventions
2. Rename the other to be more specific
3. Or merge if they're complementary

4.3 Conflicting Advice

Example: One says "always use X", another says "never use X"

Resolution Process:

1. Identify the CONTEXT for each piece of advice
2. Create nuanced guidance with conditions
3. Add examples for each scenario
4. Document when each applies

4.4 Decision Tree

Is this component new to ltk?
├── YES → Quality score >= 60?
│   ├── YES → Add with ltk conventions
│   └── NO → Skip or improve first
│
└── NO → Similar exists in ltk
    ├── Similarity >= 90% (Duplicate)
    │   └── Compare quality scores → Keep better one
    │
    ├── Similarity 70-89% (Near-Duplicate)
    │   └── Merge: combine best of both
    │
    ├── Similarity 50-69% (Related)
    │   └── Evaluate: consolidate or keep separate?
    │
    └── Similarity < 50% (Distinct enough)
        └── Quality score >= 60? → Add

Phase 5: Domain-Specific Placement

5.1 Domain Classification

5.2 Cross-Domain Components

Some components span domains. Place in PRIMARY domain, cross-reference in others:

# In primary location
---
name: component-name
related:
  - ltk-engineering/skills/related-skill
  - ltk-devops/agents/related-agent
---

Phase 6: Merge Strategies

6.1 Skill Merge Template

---
name: merged-skill-name
description: [Combined CSO-optimized description covering ALL trigger phrases]
version: 1.0.0
sources: [source1, source2]  # Attribution
---

# [Skill Title]

[Best introduction from all sources]

## [Section from Source A - if superior]

[Content]

## [Section from Source B - if unique]

[Content]

## [Merged section - combining both]

[Synthesized content taking best from each]

<!--
Merge Notes:
- Took X from source1 because: reason
- Took Y from source2 because: reason
- Combined Z because: reason
-->

6.2 Agent Merge Strategy

---
agent: merged-agent-name
description: |
  [Combined description with all use cases]
  <example>...</example>
  <example>...</example>  # Include examples from ALL sources
model: [keep more capable model]
tools: [union of all tools needed]
color: [consistent with ltk conventions]
sources: [source1, source2]
---

# [Agent Title]

[Synthesized capabilities from all sources]

## Workflow
[Best workflow, enhanced with steps from other sources]

6.3 Command Merge Strategy

Commands should generally NOT be merged - they're distinct actions. Instead:

• Keep the more complete version
• Add unique features from other version
• Ensure no naming conflicts

Phase 7: Deduplication Audit

7.1 Pre-Sync Audit

Before syncing, audit EXISTING ltk components:

# Find potential duplicates by keyword analysis
for skill in plugins/*/skills/*/SKILL.md; do
  echo "=== $skill ==="
  grep -i "description:" "$skill"
done | sort | uniq -c | sort -rn

7.2 Duplicate Detection Patterns

7.3 Post-Sync Verification

After sync, verify no duplicates introduced:

# Check for duplicate skill names
find plugins -name "SKILL.md" -exec basename {} \; | sort | uniq -c | sort -rn | head -20

# Check for duplicate agent names
find plugins/*/agents -name "*.md" -exec basename {} .md \; | sort | uniq -c | sort -rn | head -20

# Check for duplicate command names
find plugins/*/commands -name "*.md" -exec basename {} .md \; | sort | uniq -c | sort -rn | head -20

Phase 8: Output Report Format

# Submodule Sync Report

**Date:** YYYY-MM-DD
**Submodules Analyzed:** N
**Components Discovered:** N
**Components Added:** N
**Components Merged:** N
**Duplicates Removed:** N

## Similarity Analysis Summary

| Comparison | Similarity | Decision |
|------------|------------|----------|
| A vs B | 85% | Merged → A |
| C vs D | 95% | Duplicate, kept C |
| E vs F | 45% | Kept both |

## Quality Scores

| Component | Source | Score | Decision |
|-----------|--------|-------|----------|
| skill-x | submodule-1 | 82 | Added |
| agent-y | submodule-2 | 55 | Improved, then added |
| command-z | submodule-3 | 35 | Rejected (low quality) |

## Components Added

| Type | Name | Domain | Source | Notes |
|------|------|--------|--------|-------|
| skill | name | ltk-core | sub1 | New capability |

## Components Merged

| Result | Sources | Merge Strategy |
|--------|---------|----------------|
| skill-a | skill-a1 + skill-a2 | Combined best sections |

## Duplicates Resolved

| Kept | Removed | Reason |
|------|---------|--------|
| A (ltk) | A' (submodule) | ltk version more complete |

## Rejected (Quality)

| Component | Source | Score | Reason |
|-----------|--------|-------|--------|
| skill-x | sub3 | 35 | Poor formatting, incomplete |

## Action Items

- [ ] Review merged component: X
- [ ] Test new command: Y
- [ ] Consider consolidating: Z1 + Z2

Remember

1. Always do semantic analysis - Names can be deceiving
2. Quality gates are mandatory - Don't add mediocre content
3. Merge > Add - Prefer enhancing existing over adding similar
4. Attribution matters - Credit sources
5. Test after sync - Verify nothing broke
6. Document decisions - Future you will thank present you