Concern Review

concern-review

Large PRs are easier to review grouped by what the change is doing (e.g. "new retry logic", "bug fix", "reporting additions") than by a flat list of files — a file that serves two purposes should show up, sliced, in both places. This skill produces that as a static HTML page: a left sidebar to jump between concerns, one concern's files shown at a time as a single scrolling list, real unified diffs with GitHub-style coloring, and a short summary above each file's diff.

The one rule that makes this fast and safe

Your output is a small JSON blob — never the diff content itself. You decide which hunks belong to which concern and write short summaries; a Python script pulls the actual diff text from the real diff file and builds the HTML. This means:

• Your generation is small and fast (summaries + hunk-index lists, not reproduced code).
• The rendered diff can never be wrong/hallucinated — it's sliced mechanically from the same diff you read.

Do not paste diff hunks into the JSON. Reference them by index instead.

Steps

1. Get the diff into a file

Pick whichever applies:

# GitHub PR (set GIT_DIR if the repo uses jj)
GIT_DIR=$(jj git root 2>/dev/null || echo .git) gh pr diff <number> > /tmp/<slug>.diff

# local working diff (jj)
jj diff --git -r <revision> > /tmp/<slug>.diff

# local working diff (git)
git diff <base>...<head> > /tmp/<slug>.diff

Use a short <slug> you'll reuse for the other temp files (e.g. pr5276).

2. Get the authoritative hunk map

python3 ~/.claude/skills/concern-review/scripts/list_hunks.py /tmp/<slug>.diff [optional-path-substring-filter]

This prints, per file, every hunk's 0-based index, its @@ ... @@ header, and its +/- line count. These indices are what you'll reference in the JSON — don't hand-count @@ lines from the raw diff, use this output. Filter by a path substring if the diff is huge and you want one file at a time.

3. Read the diff to understand the change

Read /tmp/<slug>.diff (or grep/sed specific line ranges for very large files) to actually understand what changed — the hunk map from step 2 tells you where things are, not what they do. This is normal input-token reading; the efficiency goal is about what you write, not what you read.

4. Decide the concerns

Aim for 2-6 concerns that are genuinely distinct themes — not "misc" or one concern per file. Good concerns read like a PR description's bullet points: "new retry logic for X", "bug fix: Y", "reporting/logging additions". Each concern needs:

• key: short kebab-slug, used in DOM ids/anchors (e.g. "vpn-retry")
• title: human title, shown as the section heading
• desc: one or two sentences

5. Assign files to concerns

For each file touched by a concern, add an entry:

{ "path": "exact/path/as/printed/by/list_hunks.py", "summary": "...", "hunks": "all" }

• If all of a file's changes serve this one concern, use "hunks": "all" (or omit the key — that's the default).
• If a file's hunks serve multiple concerns, list only the relevant 0-based hunk indices for each concern, e.g. "hunks": [0, 1, 4, 5]. Every hunk in the file must be assigned to exactly one concern — check the total hunk count from list_hunks.py against your combined lists so none are silently dropped or duplicated.
• If a single hunk's lines genuinely mix two concerns (rare — usually only happens with an unrelated one-line addition riding inside a bigger hunk), assign the whole hunk to whichever concern dominates it. Don't try to split a hunk line-by-line; that produces an invalid diff.
• summary: one to three sentences on what changed in this file, for this concern and why — not a restatement of the diff. Write it like you're telling a colleague what to look for.

6. Add notes only for genuinely confusing things

Each concern may have a "notes" array (rendered as an amber "Might be confusing" callout). Reserve these for things a careful reviewer could easily miss or misjudge: a hidden invariant, duplicated logic that could drift, an intentional-looking tradeoff, a migration/compatibility implication, two call sites solving the same problem differently. Do not add navigational notes like "the rest of this file is in another section" — the UI already makes that obvious (files are listed per-concern in the sidebar), and a prior user explicitly asked for these to be removed. If nothing is genuinely confusing, omit notes or leave it empty.