Multi-document semantic comparison, difference diagnosis, and interactive merge resolution. Use when the user uploads or references multiple documents on the same topic and wants to compare, contrast, reconcile, or merge them. Trigger on phrases like "compare these documents", "what are the differences between", "merge these drafts", "which version is better", "reconcile these essays", "diff these articles", "align these texts", or when the user provides multiple files covering the same subject and asks for analysis. Also trigger when the user mentions having multiple AI-generated drafts, multiple agent outputs, or parallel writing attempts that need consolidation. Even if the user just says "help me pick the best parts from these", this skill applies.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skills-that-work-core:doc-mergeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Systematic multi-document semantic comparison and interactive merge resolution. Takes multiple
Systematic multi-document semantic comparison and interactive merge resolution. Takes multiple documents on the same topic, diagnoses their differences at multiple levels of abstraction, and guides the user through resolving conflicts to produce a single authoritative output.
Traditional text diff tools compare character-by-character. Doc-merge operates at the semantic level: it identifies differences in argumentation, framing, evidence selection, logical structure, and rhetorical strategy, even when two documents say similar things in completely different words.
The workflow has two phases:
Users can stop after Phase 1 (just want the analysis) or continue into Phase 2 (want a merged final version). Always ask after Phase 1 completes.
Goal: Produce a structured comparison report that maps differences across all input documents at multiple granularity levels.
Read all uploaded documents. For each document, extract:
Map which sections of each document correspond to each other. Documents may use different headings or ordering but discuss the same topics. Build an alignment table:
Section Topic | Doc A Section | Doc B Section | Doc C Section
---------------------|------------------|------------------|------------------
Introduction | §1 (paras 1-3) | §1 (paras 1-2) | §1 (paras 1-4)
Theoretical framing | §2 | §2 | [not present]
Empirical analysis | §3 | §4 (reordered) | §2
...
Flag sections that exist in one document but not others (unique contributions vs omissions).
For each aligned section pair/group, classify differences using the four-level taxonomy.
Read references/difference_taxonomy.md for the full classification system. The levels are:
For each difference found, record:
Phase 1 produces two complementary outputs that serve different purposes.
Read references/output_formats.md for detailed formatting templates.
A document that shows differences in context, inline within the text. This is the "see the differences" view — analogous to a code diff but operating at the semantic level.
How it works:
[UNIQUE to Doc X] markerThe annotated diff uses Markdown formatting conventions:
**[Doc A]** / **[Doc B]** prefixes to label sources>) to set off each document's version~~strikethrough~~ for content present in one document but absent in another---) between difference blocks(*) markers at points of divergence within otherwise shared sentencesThis output lets the user visually scan where and how documents differ, much like reading tracked changes in a word processor.
An analytical summary that abstracts away from the raw text and presents differences as structured, categorised decision points. This is the "understand the differences" view.
The report contains:
Ask the user:
"These are the two diagnostic views — the annotated diff shows differences in context, and the report breaks them down by type and dependency. Would you like to proceed to interactive resolution to merge these into a single document, or is this analysis sufficient for now?"
Goal: Walk the user through each difference point, collect their decisions, and produce a unified final document.
Read references/resolution_workflow.md for the detailed interaction protocol.
Before starting, construct resolution batches using the dependency graph:
Read references/batch_logic.md for the full batching algorithm.
For each batch:
For each difference, the user can:
After all batches are resolved, produce the final merged document. Also generate a brief merge log summarising each decision point and the choice made, for traceability.
All outputs are in Markdown. For the final merged document, match the genre and style of the input documents.
Read these as needed during execution:
| File | When to Read |
|---|---|
references/difference_taxonomy.md | During Step 3 of Phase 1, to classify differences |
references/alignment_strategy.md | During Step 2 of Phase 1, for structural alignment logic |
references/output_formats.md | During Step 4 of Phase 1, for annotated diff and report templates |
references/resolution_workflow.md | At the start of Phase 2, for interaction protocol details |
references/batch_logic.md | Before constructing batches in Phase 2 |
HTML templates for structured output. Use these as scaffolds — replace {{PLACEHOLDER}}
values with actual content, and duplicate or remove repeating elements as needed.
| File | Purpose |
|---|---|
assets/diagnostic_report_template.html | Phase 1 diagnostic report: stats bar, alignment table, collapsible level groups with difference entries, dependency summary |
assets/resolution_batch_template.html | Phase 2 per-batch view: progress bar, decision cards with side-by-side comparison, stakes info, resolution badges, batch decision log |
When the current platform supports HTML artifact rendering, read the appropriate template
file and populate it. When HTML is not supported, fall back to the Markdown formats
described in references/output_formats.md.
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
npx claudepluginhub zkbkb/skills-that-work --plugin skills-that-work-core