Changelog narrator

Changelog Narrator

This skill compares two versions of a business document and produces a structured, human-readable changelog — without git, CLI, or "Track Changes". Designed for non-technical users who receive updated drafts and need to understand what changed at a glance.

Input:

• Two local files (.md or .txt) in the Cowork workspace — old version (v1) and new version (v2)
• Optional: version labels if filenames are ambiguous; optional focus area (e.g., "only compare Section 3")

Output:

• Markdown changelog: Summary → Added → Removed → Modified → Notes

---

Language Detection

Detect the user's language from their message:

• If Russian (or contains Cyrillic): respond in Russian
• If English (or other Latin-script language): respond in English
• If ambiguous: respond in the language of the trigger phrase used

---

Instructions

Step 1: Identify and Validate Files

1. Check that exactly two files are provided

   • If only one file is given: stop — "Two documents are required. Please provide both the old version (v1) and the new version (v2)."
   • If no files are given: scan the Cowork workspace for .md and .txt files; list them and ask the user to specify which two to compare

2. Read both files

   • If a file is unreadable (binary, corrupted, unsupported format): stop — "Could not read [filename]. changelog-narrator works with .md and .txt files only."

3. Determine version order (which is v1, which is v2)

   • Infer from filename markers: v1/v2, old/new, draft/final, date suffixes (earlier date = v1)
   • If version order is ambiguous (e.g., strategy-a.md vs strategy-b.md): ask — "Which file is the older version?" — do not guess

Step 2: Split Documents into Comparable Units

1. Segment each document into logical units:

   • H1/H2/H3 headings → use as section labels
   • Paragraphs under each heading → compare as blocks
   • Numbered or bulleted list items → compare as individual items
   • Table rows → compare row by row

2. Build a section map for each document:

   • Key: section heading (or "Intro" for content before the first heading)
   • Value: list of content units under that heading

3. If user specified a focus area (e.g., "only Section 3" or "only the Risks section"):

   • Filter both maps to matching section only
   • Note in output: "Comparison limited to: [Section Name]"

Step 3: Compare and Classify Changes

1. Align sections by heading label across v1 and v2

2. For each content unit, classify:

   • Added: present in v2 but absent in v1
   • Removed: present in v1 but absent in v2
   • Modified: present in both, but content differs
   • Unchanged: identical in both → do NOT include in output

3. For Modified items:

   • Describe the change briefly: what was the key shift? (e.g., "Timeline changed from Q2 to Q3", "Metric updated from 10% to 15%", "Scope narrowed from 5 to 3 segments")
   • Do NOT reprint full paragraphs from both versions
   • If the change is structural (section renamed, split, merged): flag as Modified with note "Section restructured"

4. For tables:

   • Compare rows as discrete units — flag each added/removed/modified row individually
   • Do not collapse entire table into a single "Modified" entry

Edge Cases:

• Files are identical: output "No changes detected between [v1] and [v2]." Do not produce an empty changelog.
• Section exists in v2 but not in v1 → entire section is Added
• Section exists in v1 but not in v2 → entire section is Removed

Step 4: Write Summary

Write 2–3 sentences capturing:

• Overall scope of changes (how many sections affected, what type of changes dominate)
• The apparent intent behind the changes (e.g., "Scope was narrowed", "Risks section significantly expanded", "Timelines shifted across the board")
• Avoid generic statements — reference specific sections or patterns

Step 5: Format and Output Changelog

1. Assemble the changelog using the Output Format structure below
2. Populate each section: Added, Removed, Modified — each with N (count)
3. Skip any section with 0 entries (e.g., if nothing was removed, omit "Removed")
4. Add Notes section for all assumptions about version order, skipped content, focus-area limitations, table handling

---

Negative Cases

• Only one file provided: Stop — "Two documents are required. Please provide both the old version (v1) and the new version (v2)."
• No files found in workspace: Stop — "No files found. Please upload your document versions or confirm they're in the selected Cowork folder, then try again."
• File is binary/unreadable: Stop — "Could not read [filename]. changelog-narrator works with .md and .txt files only."
• More than two files provided: Clarify — "I can compare two versions at a time. Please specify which two to compare first. You can run the skill again for additional pairs."
• User asks for visual/side-by-side diff: Explain — "I produce a structured text changelog. For a visual side-by-side diff, paste both files into a tool like Diffchecker.com."

---

Output Format

## Changelog: [Document Title] — [v1 filename] → [v2 filename]

**Compared:** `[filename-v1]` vs `[filename-v2]`
**Date:** [YYYY-MM-DD]

### Summary
[2–3 sentences: overall scope and intent of changes — specific sections and patterns, not generic phrasing]

---

### Added (N)

- **[Section / Heading]:** [Brief description of what was added]
- **[Section / Heading]:** [Brief description of what was added]

### Removed (N)

- **[Section / Heading]:** [Brief description of what was removed]

### Modified (N)

- **[Section / Heading]:** [Key change — e.g., "Timeline extended from Q2 to Q3"; "Success metric changed from 10% to 15% retention"]
- **[Section / Heading → Sub-item]:** [Brief description]

---

### Notes
- [Assumption: e.g., "Treated `strategy-a.md` as v1 based on earlier file modification date"]
- [Flag: e.g., "Table in Section 4 had 3 rows added — listed under Added separately"]
- [Scope note: e.g., "Comparison limited to Section 3 as requested"]