Doc Compare

---
name: doc-compare
description: "Визуальное сравнение markdown-документов бок о бок (side-by-side) с ПОДСВЕТКОЙ ПРАВОК. Скрипт scripts/compare_docs.py режет документы на блоки (заголовки/абзацы/списки/таблицы), через difflib находит изменённые блоки и подсвечивает: слева красным (удалено/изменено), справа зелёным (добавлено/изменено); внутри правок — пословная подсветка (зачёркнутое красным / добавленное зелёным). Кнопка «Только изменения» прячет неизменённые блоки. Поддерживает подтягивание версии из публичного GitHub-репозитория через gh (префикс gh:owner/repo@ref:path) и режим --diff (построчная таблица difflib). Триггеры: 'сравни документы', 'doc compare', 'side-by-side', 'визуально сравнить', 'diff docs', 'сравнение оферт', 'сравнить с опубликованным', 'покажи где правки', 'подсвети изменения'."
license: MIT
metadata:
  author: best
  version: 1.1.1
  compatibility: "Requires Python 3, gh CLI (для gh: источников)"
when_to_use: "Use when you need to visually compare two versions of a markdown document и сразу ВИДЕТЬ, где были правки (например, локальный драфт vs опубликованное на GitHub Pages), рецензировать правки в офертах/договорах бок о бок. Триггеры: 'сравни доки', 'doc compare', 'side-by-side', 'сравнить с публичным', 'где правки', 'покажи изменения', 'diff оферту'."
---

# Doc Compare

> Визуальное сравнение markdown-документов с подсветкой правок: две колонки (слева/справа) в одном окне браузера, вкладки на каждую пару, изменённые места подсвечены, кнопка «Только изменения».

## 🎯 When to use

- Нужно визуально сравнить локальный драфт с опубликованной версией (оферты `lovii_docs` vs `axiiom-ru/lovii`).
- Сразу видеть, ГДЕ были правки: изменённые блоки подсвечены, внутри — пословно.
- Свернуть всё лишнее кнопкой «Только изменения» и смотреть только затронутые места.

## 📦 Files

- `SKILL.md` — этот файл
- `scripts/compare_docs.py` — сборщик side-by-side с подсветкой правок

## 🧰 Usage

```bash
# Локальный драфт vs опубликованное в публичном репо (gh: подтягивает через gh api)
python3 ~/.config/opencode/skills/doc-compare/scripts/compare_docs.py \
  --pair "Опубликовано|gh:axiiom-ru/lovii@main:docs/Публичная_оферта.md|Драфт|./docs/Публичная_оферта.md" \
  --pair "Опубликовано|gh:axiiom-ru/lovii@main:docs/Оферта_присоединения.md|Драфт|./docs/Оферта_присоединения.md"

# Построчная таблица difflib (альтернатива бок-о-бок)
python3 ~/.config/opencode/skills/doc-compare/scripts/compare_docs.py \
  --diff --pair "Старая|a.md|Новая|b.md"

# Не открывать браузер, только сгенерировать файл
python3 ~/.config/opencode/skills/doc-compare/scripts/compare_docs.py --no-open --pair "L|l.md|R|r.md" --out /tmp/cmp.html
```

Формат `--pair`: `"ЛеваяМетка|левый_файл|ПраваяМетка|правый_файл"`.
Префикс `gh:owner/repo@ref:path` у любого из файлов = подтянуть из GitHub через `gh api` (ветка `ref` необязательна, по умолчанию `main`).

## 🔬 Как читать результат

- **Без `--diff`**: две колонки. Слева = первая версия (обычно опубликованная/старая), справа = вторая (драфт/новая).
  - 🟥 красная полоса слева — блок удалён или изменён (старое слово зачёркнуто).
  - 🟩 зелёная полоса справа — блок добавлен или изменён (новое слово подсвечено).
  - Внутри изменённого блока слова подсвечены пословно.
  - Кнопка **«Только изменения»** (в шапке) прячет всё неизменённое — остаются только затронутые места.
- **С `--diff`**: классическая таблица difflib — добавленные строки зелёные, удалённые красные, изменённые жёлтые.

## Boundaries

- Do not use for general document quality audits; use `chronos`.

## Evidence and completion gate

Run the documented command against the user’s actual input. Report the command, exit status, files changed or produced, and relevant stdout/stderr. Separate blocked or pre-existing failures from failures introduced by the current work. Do not call the result complete when the script was only described or when an artifact was not reopened and checked.