Reviewable Branch Diffs

Objective

Make the aggregate Git branch diff easy for a human to review. Coding standards describe good code; this skill decides which changes on the current branch should be made to satisfy those standards. Leave unrelated pre-existing violations in place.

The standards themselves come from user instructions, other skills, repository instructions, or tools—not from this skill.

1. Establish the Git baseline

Identify the intended integration branch using Git only:

1. If the user or repository workflow explicitly identifies the integration branch, use it.
2. Otherwise, determine the relevant remote with git remote. If more than one exists, use available Git tracking/configuration information to select the right one; do not silently pick an arbitrary remote.
3. Resolve that remote's default branch via git symbolic-ref --quiet --short refs/remotes/<remote>/HEAD. If the symbolic ref is missing, consult git ls-remote --symref <remote> HEAD when network access is appropriate. This queries the remote's HEAD, not the current checkout's HEAD.
4. Use the resulting remote-tracking branch as the candidate integration branch. A remote default is not proof of the branch's actual merge destination. If evidence conflicts or is ambiguous, establish the target before applying scope-sensitive rules.
5. Ensure the candidate ref is present and sufficiently current (fetch when appropriate).

Inspect the committed changes and the prospective complete working-tree diff:

git diff --find-renames <base-ref>...HEAD
git diff --find-renames "$(git merge-base <base-ref> HEAD)"
git ls-files --others --exclude-standard

The three-dot form compares committed branch changes with their merge base. The second command compares that same baseline with the current working tree, including staged and unstaged tracked changes. The last command discovers untracked files that neither diff includes.

2. Determine the eligible change scope

A change to one line does not make an entire function or file eligible for reorganization.

3. Apply conventions within that scope

Structural organization

• Existing function: Keep its location when the feature changes a line inside it, even if a separate ordering convention would place it elsewhere. Otherwise, a small logic change becomes distant deletion/addition blocks.
• New function: Insert it at the location prescribed by the applicable coding rules; it has no prior location to preserve.

Declarations and type annotations

Apply required typing conventions to newly introduced functions and parameters. Do not retrofit unrelated existing signatures. When a feature changes an existing function, keep annotation changes limited to genuinely new or modified declarations and avoid incidental signature reflow.

Formatting

Format newly introduced or necessarily modified code without reformatting unrelated existing lines. If a formatter rewrites larger regions, retain the required edits and revert unrelated churn where feasible.

If a mandatory formatter or check requires wider changes, identify the constraint and make the smallest technically valid change; do not silently accept a large formatting-only diff.

4. Preserve the branch-level review boundary

A separate cleanup commit on the same branch still appears in its aggregate diff. Unrelated cleanup needs a separate scope, not merely a separate commit.

5. Verify the result

1. Reinspect the full diff against the resolved baseline, including outstanding tracked edits and untracked files.
2. Check each moved block, reflowed signature, and formatting-only hunk for a necessary feature-related reason. Remove incidental cleanup.
3. Ensure the actual behavior change remains visible as a localized diff where feasible, and run relevant tests.
4. Report any unavoidable scope expansion or unresolved baseline ambiguity.

This skill is agent guidance, not a guaranteed Git policy gate. Where enforcement must be deterministic, use an independently validated checker or hook appropriate to the agent runtime.