explain-branch-changes

Explain Branch Changes

Turn the current branch's changes into a briefing a person who has never seen code can read. The reader may be a product manager, designer, support agent, marketer, or executive. They care about what changes for users and the business — never about how the code does it.

Write the briefing in the language the user communicates in. If the user writes in Russian, the briefing is in Russian.

The process:

1. Collect the branch changes (git)
2. Mine the changes and project docs for product meaning
3. Translate to human language and deliver the briefing

Step 1: Collect the Changes

Detect the base branch and gather the raw material:

BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$BASE" ]; then
  BASE=$(git rev-parse --verify main >/dev/null 2>&1 && echo main || echo master)
fi
git log $BASE..HEAD --pretty=format:"%h %s%n%b"
git diff $BASE...HEAD --stat
git diff $BASE...HEAD

Include uncommitted work (git status --short, git diff HEAD) if present — the reader wants the state of the branch, not just its commits.

Handle the edge cases in the reader's terms, not git's:

• Not a git repository → say this folder has no change history to read, and stop.
• On the base branch / no changes → say there is no work-in-progress here; offer to describe what shipped recently (last ~10 commits on the base branch) instead.
• Huge diff (thousands of lines) → work from --stat, commit messages, and targeted reads of the most-changed and most user-facing files. Never skip Step 2 because the diff is big.

Step 2: Mine for Product Meaning

The diff says what changed; the surrounding context says why. Gather both:

• Commit messages and branch name — often contain the intent and ticket IDs.
• PR description — gh pr view if a PR exists (ignore errors if not).
• User-visible strings in the diff — UI labels, button texts, error messages, emails, notification texts, translation files. These are the single best source for a product summary: they show exactly what a user will see.
• Docs touched or nearby — README, CHANGELOG, docs/, design docs, .archcore/ or similar knowledge bases. If the project documents the changed area, read it to name features the way the project names them.
• Tell-tale files — migrations (data storage changed), feature flags (built but switched off), config/infra files, dependency manifests, test-only changes. See references/change-types.md for how to recognize and phrase each type.
• The code itself — read enough of the changed code to understand the actual behavior change. Use it for understanding only; none of it surfaces in the output.