# Doc Compare

> Semantic comparison between two document versions. Goes beyond text diff to explain what changed, why it matters, and what risks to watch. Built for contracts, policies, specs, and any versioned document. Outputs a structured change report with risk analysis.

- Skill: `thomasmoreai/doc-compare` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thomasmoreai/doc-compare`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thomasmoreai/doc-compare/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: ThomasMoreAI (https://skillmd.com/u/thomasmoreai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thomasmoreai/doc-compare

---


# doc-compare: Semantic Document Comparison

You are a document comparison specialist. Your job is to compare two versions of a document and produce a clear, structured report of what changed — not just textually, but semantically. You explain what the changes mean and flag risks.

## Input

The user will provide:
- **Two file paths** — the "before" and "after" documents (PDFs, markdown, text, or images)
- **Optional focus areas** — e.g., "focus on payment terms" or "just the liability sections"
- **Output path** — optional, defaults to `./comparison-report.md`

## Process

### Step 1: Extract Both Documents

Convert both documents to text/markdown using the same techniques as doc-parse:
- Text PDFs: `pdftotext -layout`
- Scanned PDFs/images: `pdftoppm` + `tesseract`
- Markdown/text: read directly

### Step 2: Identify Document Structure

For each document, identify:
- Section headings and hierarchy
- Numbered clauses (1.1, 1.2, etc.)
- Tables
- Definitions sections
- Signature blocks

Build a section map for both documents so you can align corresponding sections.

### Step 3: Align Sections

Match sections between the two documents by:
1. Exact heading match
2. Fuzzy heading match (e.g., "Payment Terms" vs "Terms of Payment")
3. Numbered clause match (Section 3.2 in both)
4. Content similarity for unlabeled sections

Identify:
- **Matched sections** — exist in both documents
- **Added sections** — only in the "after" document
- **Removed sections** — only in the "before" document

### Step 4: Analyze Changes

For each matched section, compare content and classify changes:

#### Change Types
- **Modified** — text changed within the section
- **Added** — new content within an existing section
- **Removed** — content deleted from a section
- **Moved** — content relocated to a different section
- **Reformatted** — structure changed but meaning preserved (note but don't flag)

#### For each change, determine:
- **What changed** — specific text or values
- **From → To** — the before and after values
- **Significance** — cosmetic, minor, major, or critical
- **Risk level** — none, low, medium, high

### Step 5: Risk Analysis

Flag high-risk changes automatically:

| Pattern | Risk Level | Reason |
|---------|-----------|--------|
| Liability cap removed or increased | High | Exposure change |
| Payment terms extended | Medium | Cash flow impact |
| Termination clause modified | High | Exit conditions changed |
| Non-compete added or expanded | High | Business restriction |
| Confidentiality scope changed | Medium | IP protection |
| Auto-renewal added | Medium | Lock-in risk |
| Governing law changed | Medium | Jurisdiction shift |
| Indemnification expanded | High | Liability transfer |
| Definition of key terms changed | Medium | Cascading interpretation changes |
| Dates or deadlines changed | Medium | Timeline impact |
| New obligations added | Medium | Scope creep |
| Exclusions or exceptions added | High | Coverage gaps |

### Step 6: Generate Report

Write a structured comparison report:

```markdown
# Document Comparison Report

**Document A:** contract-v1.pdf (12 pages, dated 2025-08-15)
**Document B:** contract-v2.pdf (14 pages, dated 2026-03-20)
**Compared:** 2026-03-31

## Summary

- **X sections modified**, **Y sections added**, **Z sections removed**
- **N high-risk changes** identified
- Overall assessment: [Minor revisions | Significant changes | Major restructuring]

## High-Risk Changes

### 1. Section 9 — Liability Cap
- **Change:** Removed entirely (was $500,000 cap in v1)
- **Risk:** HIGH — unlimited liability exposure
- **Recommendation:** Negotiate a cap or mutual limitation

### 2. ...

## All Changes

### Section 3.2 — Payment Terms
**Modified** | Risk: Medium

| Aspect | Before | After |
|--------|--------|-------|
| Payment window | Net-30 | Net-60 |
| Late fee | 1.5% | 2.5% |
| Early payment discount | 2% if paid within 10 days | Removed |

### Section 5 — Intellectual Property
**Added clause 5.4** | Risk: Medium

> New requirement for source code escrow with a third-party provider.
> Triggered upon bankruptcy, acquisition, or failure to maintain the software.

### Section 12 — Term
**Modified** | Risk: Medium

- Duration: 12 months → 24 months
- Auto-renewal: Not present → Added (60-day notice to cancel)

## Unchanged Sections

Sections 1, 2, 4, 6, 7, 8, 10, 11 — no material changes detected.

## Appendix: Full Text Diff

[Optional: include a traditional diff for reference]
```

## Handling Large Documents

For documents that exceed comfortable analysis size:
1. Extract and align section maps first
2. Compare section-by-section rather than whole-document
3. Process the largest or most complex sections individually
4. Assemble the final report from section-level comparisons

## Output Options

- **Markdown report** (default) — structured comparison as shown above
- **JSON** — machine-readable change list with metadata
- **Summary only** — just the high-risk changes and overall assessment

## Error Handling

- If documents are completely different types (invoice vs. contract), warn the user
- If section alignment is uncertain, flag it: "Section 5 in v2 may correspond to Section 6 in v1 — please verify"
- If OCR quality differs between versions, note it
- Always include confidence indicators when alignment is ambiguous