Branch Diff Three-Line Summary

Produce a compact explanation of what a Git branch changes, based on the committed diff from the default branch.

Arguments

$ARGUMENTS takes the form [<branch> | <PR number>] [--expertise high|medium|low]. The --expertise option may appear before or after the target.

First, take out --expertise <level> if present. It overrides the expertise value from the configuration for this run only. If --expertise has no value, or the value is not one of high, medium, or low, say so in one line and stop; do not fall back silently, because the user asked for a level explicitly.

What remains after removing the option may be empty, a branch name, or a PR number.

• Empty: summarize the current branch.
• Branch name: summarize that branch. Use origin/<name> if the local branch does not exist.
• PR number (digits only): resolve the head with

  gh pr view <n> --json headRefName,headRepositoryOwner,isCrossRepository

  For a same-repo PR, fetch and use the head branch:

  git fetch --quiet origin <headRefName>

  and take <target> as origin/<headRefName>. For a cross-repository (fork) PR, origin/<headRefName> does not exist, so fetch it into a local ref instead:

  git fetch --quiet origin pull/<n>/head:refs/branch-tldr/pr-<n>

  and take <target> as refs/branch-tldr/pr-<n>. If gh is unavailable or either command fails, say so in one line and stop.

Below, <target> means the resolved ref (HEAD when no argument is given), and <base> means the comparison base resolved in step 4 of the workflow.

Configuration

The config file always lives at ~/.config/branch-tldr/config.toml, regardless of where this skill itself is installed:

[output]
max_line_length = 100
style = "日本語の場合は常体 (だ・である調) を使う。"
expertise = "medium"

• max_line_length: maximum characters per bullet body, excluding the leading - . Count full-width and half-width characters as one each.
• style: an extra free-text instruction about writing style. An empty string means no extra instruction.
• expertise: how much technical background the reader has, one of high, medium, or low. See "Expertise levels" under the output rules. The --expertise argument takes precedence over this value.

The values shown above are the built-in defaults. If the file does not exist, use those defaults and continue. Do not create the file and do not mention that it is missing; the output must stay three bullets. config.toml.template in this skill's directory exists only as a starting point for users who want to override the defaults by hand.

Do not rely on a TOML parser. Read the file with cat and pick up max_line_length = <integer>, style = "<string>", and expertise = "<string>" under [output]. Apply these fallbacks silently:

• Missing key, a max_line_length that is not a positive integer, or an expertise other than high, medium, or low: use the built-in default shown above.
• style = "" set explicitly: no extra style instruction. This differs from a missing style, which falls back to the default 常体 instruction.

Workflow

1. Load the configuration as described above.
2. Confirm you are in a Git repository:

   git rev-parse --show-toplevel

3. Identify the default branch:

   git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##'

   If origin/HEAD is unavailable, fall back to main if it exists, then master if it exists.
4. Refresh the comparison base so the summary is not made against a stale default branch, then resolve <base>:

   git fetch --quiet origin <default-branch> 2>/dev/null || true
   git rev-parse --verify --quiet origin/<default-branch>

   <base> is origin/<default-branch> when that ref resolves, otherwise the local <default-branch>. Use <base> in every command below; never assume the origin/ prefix, because a repository without an origin remote only has the local branch.
5. Detached HEAD needs no special handling: treat HEAD as the target as usual.
6. Get the scope first. The ... form already compares from the merge base, so no separate merge-base call is needed:

   git --no-pager diff --stat <base>...<target>
   git --no-pager diff --name-status <base>...<target>

   If --stat reports no changes, the branch has nothing of its own relative to <base> — this covers <target> being the default branch as well as an up-to-date branch. Return exactly three bullets saying there are no branch-specific changes and naming <base>. Judge this from the emptiness of the diff, not from the branch name: a local default branch that is ahead of <base> does have a real diff and must be summarized normally.
7. Read the patch with a size guard:
   • If the total changed lines in --stat are 800 or fewer, read the full patch:

     git --no-pager diff <base>...<target>

   • Otherwise, do not dump the full patch. Exclude generated and vendored files (*.lock, package-lock.json, composer.lock, dist/, build/, vendor/, node_modules/, minified assets, snapshot files), then read the remaining files one at a time with git --no-pager diff <base>...<target> -- <path>, starting from the files with the most changed lines, until the intent of the branch is clear. Use git log --oneline <base>..<target> as an additional hint for intent.
8. Base the summary on the actual diff, not only file names. Understand behavior, not just which files moved.
9. Only committed changes are in scope. Ignore staged and unstaged working tree changes, and do not mention them.

Output rules

• Output exactly three bullet points, no heading and no extra prose.
• Give each bullet a fixed role:
  1. What changed: the main functional or structural change of the branch.
  2. How or why: the approach taken, or the reason it was needed, as far as the diff shows it.
  3. Impact: affected scope, behavioral risk, or what to check before merging or applying.
• Match the user's language. If the user asks in Japanese, answer in Japanese.
• Apply the style instruction from the configuration. With the default, Japanese output uses plain form (常体), not polite form.
• Keep each bullet body within max_line_length characters. If a bullet runs over, cut detail until it fits rather than wrapping.
• Prefer explaining user-visible or operational impact over listing filenames.
• Include filenames only when they clarify the change. At medium and low, rephrasing takes precedence over this.
• Do not include commands, raw diff snippets, commit hashes, or speculation beyond what the diff supports.
• Do not write a commit message or PR body unless the user explicitly asks for that instead.

Expertise levels

Write for the resolved expertise level. The level changes only the wording; the three bullet roles and max_line_length stay the same at every level.

• high: for engineers who work with the changed technology. Use domain terms and identifiers (resource types, variable names, filenames) as they are. In the impact bullet, state what to check before merging or applying.
• medium: for readers who know software in general but not this area. Replace tool-specific terms and identifiers with plain descriptions of what they do (for example, "permission settings" instead of "IAM"). In the impact bullet, first say whether behavior changes right away.
• low: for non-engineers. Use no technical terms. Explain what gets better and how it relates to users or day-to-day work.

Good output shape

high:

- 新リージョン向けの Terraform 設定を追加し、既存リージョンとの差分を最小限に抑えている。
- IAM と provider 設定を新リージョン向けに調整し、環境固有の値を変数へ分離した。
- 既存環境には影響しない追加変更だが、適用前に新リージョン向けの plan 確認が必要である。

medium:

- 新しい地域のデータセンターでもシステムを動かせるよう、インフラの構成定義を追加した。
- 権限や接続先の設定を新しい地域に合わせ、環境ごとに変わる値は一か所にまとめて差し替えやすくした。
- 既存の環境は変わらない。ただし反映する前に、新しい地域で何が作られるかの事前確認が必要である。

What to avoid

- Changed 12 files.
- Updated infra/env/example/main.tf.
- Looks good.

This is too file-list oriented and does not explain the intent or impact of the branch.