Diff Analysis

Diff Analysis

Concept of the skill

Use when analyzing git diff, reviewing a patch before commit, or explaining what a changeset does.

Domain Context

What is this skill? This skill provides disciplined diff analysis for AI agents: reading code changes as a structured before/after artifact, isolating semantic changes from formatting noise, tracing blast radius across files, and extracting review-ready findings from a patch. Covers unified diff anatomy, hunk-by-hunk interpretation, scope validation, hidden-risk scanning, and intent-vs-diff comparison. Use when analyzing git diff, reviewing a patch before commit, or explaining what a changeset actually does. Do NOT use for full code-review verdicts (use code-review), git workflow decisions (use version-control), or pixel/image comparison (use playwright-cli or visual diff tooling).

Key Files

Coverage

This skill covers reading and interpreting unified diffs and patches: the anatomy of diff --git output, hunk-by-hunk semantic extraction, file-level change classification (rename, mechanical rewrite, local logic edit, contract edit, test-only edit), separating signal from formatting noise, blast radius estimation for changed contracts and types, intent-vs-diff mismatch detection, and writing concise behavior-focused diff summaries. Does not cover full code review verdicts, git workflow/branching decisions, or visual/pixel comparison.

Philosophy of the skill

Agents that skim diffs miss hidden behavior changes buried in formatting churn. A one-line guard removal inside a 300-line reformat can silently widen access. This skill exists because agents need a repeatable reading discipline -- structure first, meaning second, risk last -- instead of narrating every added and removed line equally. Without it, agents produce line-by-line restatements that miss the semantic delta and say "looks safe" without naming the blast radius.

A diff is not just a list of changed lines. It is a compact representation of intent, scope, and risk. This skill helps agents read a patch accurately, separate real behavior changes from noise, and turn raw hunks into useful conclusions.

For real repo-grounded examples, read references/repo-diff-patterns.md and references/diff-reading-checklist.md when you need concrete patch shapes instead of the general rubric.

1. What This Skill Owns

2. The Diff Reading Loop

Read diffs in this order:

1. Identify the file set.
2. Classify each file by change type.
3. Read hunk headers before line edits.
4. Extract semantic change from each hunk.
5. Check for scope mismatch or hidden blast radius.
6. Summarize intent, risk, and verification needs.

Do not start by reading every added and removed line equally. Start from structure, then meaning.

3. Diff Anatomy

4. File-Level Change Classification

Before reading hunks, tag each changed file.

This classification decides how deeply to inspect the diff.

5. Semantic Extraction Per Hunk

For each hunk, answer four questions:

1. What behavior or contract existed before?
2. What behavior or contract exists now?
3. Is the change additive, restrictive, or substitutive?
4. What adjacent path could now behave differently?

Hunk interpretation rules

• A one-line edit can still be a contract break.
• Large churn can still be mostly noise.
• Added guards often narrow behavior; removed guards widen risk.
• Type-only changes can imply runtime consequences if APIs or assumptions shift.

6. Noise vs Signal

Signal extraction rules

• First identify files with likely semantic impact.
• Then ignore purely cosmetic churn only after proving it is cosmetic.
• If one hunk mixes formatting and behavior, rewrite the summary around the behavior change only.

7. Blast Radius Checks

After understanding the diff itself, ask what else the patch implicitly touches.

This skill does not require opening every dependent file. It requires naming the probable risk surface correctly.

8. Intent vs Diff

Compare the stated goal against the actual patch.

If the diff and stated intent disagree, the patch needs clarification or further work.

9. Good Diff Summaries

A good summary says why the change matters, not just what lines moved.

Use this format

• File scope: which files changed and what kinds of changes they represent
• Semantic delta: what behavior or contract changed
• Risk surface: where regressions could now appear
• Verify next: what should be tested or re-read next

Avoid

• line-by-line narration of the whole patch
• repeating obvious rename churn
• calling a diff safe without naming the risk surface

10. Boundaries

• Use code-review when you need a full review verdict and comment severity.
• Use version-control for branching, rebasing, squash, release, or provenance policy.
• Use playwright-cli or visual diff tools for screenshots and pixel comparison.
• Use scanning when you need to move from a diff into exact files and line slices efficiently.

Verification

After applying this skill, verify:

• I classified the file set before reading hunks deeply.
• I used hunk context, not only added/removed lines.
• I separated semantic change from cosmetic noise.
• I identified the likely blast radius of the patch.
• I compared the diff against the claimed intent.
• My summary explains behavior change, risk, and next verification step.
• I did not produce a line-by-line narration of the whole patch.
• I named the risk surface explicitly, not just "looks safe."

Do NOT Use When

Skill Graph context

Classification

• Subject: quality-assurance
• Public: true
• Domain: quality/doctrine
• Scope: Use when analyzing git diff, reviewing a patch before commit, or explaining what a changeset does. Covers unified diff anatomy, hunk interpretation, semantic-vs-formatting separation, blast-radius tracing, hidden-risk scanning, and intent-vs-diff comparison. Do NOT use for full code-review verdicts (use code-review), git workflow decisions (use version-control), or visual diffs.

When to use

• Triggers: diff-skill

Related skills

• Verify with: refactor, snapshot-testing
• Related: version-control, semantics

Keywords

• git diff, unified diff, patch analysis, changeset review, diff analysis, read a diff