change-log

Change Log

Overview

After every feature or bug fix is complete, add an entry to CHANGELOG.md. The log is written for business users, not developers — it powers the product updates blog. Use plain language that a non-technical person would understand.

When to Use

• After completing a feature (invoked by plan-driven-development and bug-fix automatically)
• After any user-facing change ships
• Do NOT log internal refactors, test-only changes, or dev tooling updates

Format

# Change Log

## 2026-03-20
- You can now see exactly which articles were added, updated, or deleted after each sync

## 2026-03-18
- Fixed an issue where disconnecting a connector would sometimes leave behind stale data

Finding the existing CHANGELOG (do this BEFORE writing)

Creating a duplicate CHANGELOG.md is the most common failure mode of this skill. You must exhaustively search for an existing one before creating a new file. Run all of these steps in order and only fall through to the next if the previous turned up nothing:

1. Check CLAUDE.md for an explicit path. Grep the repo's CLAUDE.md files for CHANGELOG — project owners often pin the canonical path there (e.g., "the canonical changelog is at CHANGELOG.md at the repo root"). If CLAUDE.md names a path, use that path and skip the rest.

   grep -nH -i "changelog" CLAUDE.md ./**/CLAUDE.md 2>/dev/null
   

2. Find the repo root, then look for CHANGELOG.md at the root. Do not assume your current working directory is the root — skills are often invoked from a subdirectory (e.g., chat-ui/, frontend/, apps/web/).

   ROOT="$(git rev-parse --show-toplevel)"
   ls "$ROOT"/CHANGELOG.md 2>/dev/null
   

3. Glob the entire repo for any CHANGELOG.md (case variants included), excluding vendored dirs. If matches exist, the canonical one is almost always at the repo root — pick that one. If multiple non-vendored copies exist, stop and ask the user which is canonical; do not silently pick one or create a third.

   find "$ROOT" -iname "CHANGELOG*.md" \
     -not -path "*/node_modules/*" \
     -not -path "*/.next/*" \
     -not -path "*/.venv/*" \
     -not -path "*/venv/*" \
     -not -path "*/dist/*" \
     -not -path "*/build/*" \
     -not -path "*/.claude/*"
   

4. Only if all of the above return nothing may you create CHANGELOG.md at the repo root ($ROOT/CHANGELOG.md) with the # Change Log heading and today's entry. Never create it in a subdirectory like chat-ui/CHANGELOG.md or frontend/CHANGELOG.md — the root is the canonical location.

Do not create a new CHANGELOG.md just because the existing one isn't where you expected, or because your cwd is a subdirectory and you didn't find one there. A "missing" changelog almost always means you searched the wrong directory.

Rules

• One entry per feature or fix. One sentence. Two sentences max for small features. Up to three sentences for large features.
• Use simple-design-principles language. No jargon, no technical terms. Write what the user can now do or what got better, not what code changed.
• Date format: YYYY-MM-DD. Use today's date.
• File location: CHANGELOG.md at the repo root. See "Finding the existing CHANGELOG" above — always search first, never create a duplicate.
• Append new dates at the top (most recent first), below the # Change Log heading.
• Group entries under the same date if multiple changes ship on the same day.
• Don't log the same change twice. If a feature spans multiple milestones, log it once when the full feature is complete.

Language Examples

Don't	Do
"Added sync_run_changes table and API endpoint"	"You can now see which articles changed after each sync"
"Fixed null pointer in webhook handler"	"Fixed an issue where syncs would sometimes fail silently"
"Refactored connector registry to use ABC pattern"	(Don't log — internal refactor, not user-facing)
"Implemented incremental reindexing with changed_records"	"Syncs are now faster — only changed articles are re-processed"