/smart-merge Command

Version: 1.0.0 Category: Documentation Status: Active

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Usage

# Analyze two files for similarity
/smart-merge --analyze docs/v1/readme.md docs/v2/readme.md

# Merge two files with smart strategy
/smart-merge docs/adr-v1.md docs/adr-v2.md -o docs/adr-merged.md --llm

# Find similar files in directory
/smart-merge --find docs/ --pattern "*.md" --threshold 0.6

# Dry run (preview only)
/smart-merge file1.md file2.md --dry-run

Synopsis

/smart-merge <file_a> <file_b> [options]
/smart-merge --find <directory> [options]
/smart-merge --analyze <file_a> <file_b>

Description

Intelligent document merging command that analyzes similar files, detects conflicts, and produces unified merged outputs. Supports LLM-powered conflict resolution for smart merging of documentation, ADRs, and configuration files.

Usage

Analyze Two Files

Compare two files for similarity and get merge recommendation:

/smart-merge --analyze docs/v1/readme.md docs/v2/readme.md

Output:

SMART MERGE ANALYSIS
============================================================
File A: docs/v1/readme.md
File B: docs/v2/readme.md
────────────────────────────────────────────────────────────
Lines: A=245, B=312
Sections: A=12, B=15
Identical hashes: false
────────────────────────────────────────────────────────────
Identical sections: 8
Different sections: 4
Only in A: 0
Only in B: 3
────────────────────────────────────────────────────────────
Similarity Score: 72.5%
Recommendation: DIVERGED - Smart merge recommended
============================================================

Merge Two Files

Merge files with specified strategy:

# Smart merge with LLM
/smart-merge docs/adr-v1.md docs/adr-v2.md -o docs/adr-merged.md --llm

# Prefer longer version
/smart-merge config-a.yaml config-b.yaml -o config.yaml --strategy longer

# Dry run (preview only)
/smart-merge file1.md file2.md --dry-run

Find Similar Files

Scan directory for potential duplicates:

/smart-merge --find docs/ --pattern "*.md" --threshold 0.6

Output:

Found 3 similar file pairs:

  92.5% similar:
    docs/03-architecture/ADR-EXPORT-DEDUP-SYSTEM.md
    docs/03-architecture/adrs/ADR-EXPORT-DEDUP-SYSTEM.md

  78.3% similar:
    docs/guides/setup-v1.md
    docs/guides/setup-v2.md

  61.2% similar:
    docs/api/auth.md
    docs/api/authentication.md

Options

Option	Short	Description
--analyze	-a	Analyze similarity without merging
--find	-f	Find similar files in directory
--output	-o	Output file path
--strategy	-s	Merge strategy: smart, prefer_a, prefer_b, longer
--llm		Use LLM for conflict resolution
--dry-run	-n	Preview merge without writing
--pattern	-p	File pattern for --find (default: *.md)
--threshold	-t	Similarity threshold 0-1 (default: 0.5)
--json	-j	Output as JSON

Merge Strategies

Strategy	When to Use
smart	Complex documents with meaningful differences (requires --llm)
prefer_a	When first file is known to be authoritative
prefer_b	When second file is known to be authoritative
longer	When longer content is likely more complete

Examples

Example 1: ADR Consolidation

# Step 1: Analyze two versions of an ADR
/smart-merge --analyze \
  docs/draft/ADR-001-feature.md \
  docs/03-architecture/adrs/ADR-001-feature.md

# Step 2: Merge (keep in canonical location)
/smart-merge \
  docs/draft/ADR-001-feature.md \
  docs/03-architecture/adrs/ADR-001-feature.md \
  -o docs/03-architecture/adrs/ADR-001-feature.md \
  --strategy longer

# Step 3: Clean up draft version
rm docs/draft/ADR-001-feature.md

Example 2: Documentation Audit

# Find all potential duplicates
/smart-merge --find docs/ --pattern "*.md" --threshold 0.7 --json > duplicates.json

# Review and process
cat duplicates.json

Example 3: Smart Merge with LLM

# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY="sk-..."

/smart-merge \
  feature-spec-draft.md \
  feature-spec-review.md \
  -o feature-spec-final.md \
  --strategy smart \
  --llm

Implementation

The command invokes scripts/smart-merge.py:

# Underlying script calls
python3 scripts/smart-merge.py analyze FILE_A FILE_B
python3 scripts/smart-merge.py merge FILE_A FILE_B -o OUTPUT --strategy STRATEGY
python3 scripts/smart-merge.py find DIRECTORY --pattern PATTERN --threshold THRESHOLD

Integration

With document-merger Agent

Task(
  subagent_type="document-merger",
  prompt="Use /smart-merge to consolidate the duplicate ADRs"
)

With Pre-commit Hook

# .claude/hooks/pre-commit.yaml
- name: detect-duplicates
  command: python3 scripts/smart-merge.py find . --pattern "*.md" --threshold 0.9
  on_match: warn

With /cx /cxq

# Find related documents in context
/cxq "export dedup" --files

# Then merge if duplicates found
/smart-merge detected-file-a.md detected-file-b.md

Error Handling

Error	Meaning	Resolution
File not found	One or both files don't exist	Check paths
LLM unavailable	ANTHROPIC_API_KEY not set	Set key or use --strategy longer
Binary file detected	Can't merge binary files	Use appropriate tool
No sections found	File doesn't use markdown headings	Manual merge required

Best Practices

1. Always analyze first before merging
2. Use --dry-run to preview changes
3. Backup via git before merging
4. Review merged output before committing
5. Delete redundant file after successful merge
6. Update references pointing to old file

Related

• Script: scripts/smart-merge.py
• Agent: agents/document-merger.md
• Skill: skills/smart-merge/SKILL.md
• Hook: hooks/smart-merge.md

Success Output

When merge completes successfully:

✅ COMMAND COMPLETE: /smart-merge
Files: <file_a> + <file_b>
Similarity: X%
Strategy: <smart|prefer_a|prefer_b|longer>
Output: <path or "preview only">

Completion Checklist

Before marking complete:

• Files analyzed for similarity
• Merge strategy applied
• Conflicts resolved
• Output written (unless --dry-run)
• Result verified

Failure Indicators

This command has FAILED if:

• ❌ File not found
• ❌ Binary file detected
• ❌ LLM unavailable (if --llm)
• ❌ Merge produced errors

When NOT to Use

Do NOT use when:

• Files are binary
• Need git merge (use git directly)
• Files completely different

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip analysis	Wrong strategy	Always analyze first
Merge without backup	Data loss	Use git for safety
Forget cleanup	Duplicates remain	Delete old file

Principles

This command embodies:

• #6 Clear, Understandable - Similarity scoring
• #9 Based on Facts - Analysis-based decisions
• #3 Complete Execution - Full merge workflow

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Author: CODITECT Core Team Created: 2025-12-11