review-diff

Skill: Review Diff

Purpose

Review onlycurrent changes(git diff: staged + unstaged + optional untracked files) across 5 dimensions: intent / impact, regression / correctness, breaking change / compatibility, side effects / idempotency, observability. Produce a scope-only findings list as orchestrate-code-review 's scope-step aggregation input.

Do not perform architecture / security / language / framework-specific analysis—these belong to the corresponding atomic skills.

Core Objective

Primary objective: produce a 5-dimension findings list only for the diff scope (including untracked files).

Success criteria(all must be satisfied):

✅ Diff scope only: review only the changeset; do not expand into repository-level / architecture / security / language-specific checks
✅ Full 5-dimension coverage: intent / impact, regression / correctness, breaking change / compatibility, side effects / idempotency, observability
✅ Format compliance: each finding includes location / category=scope / severity / title / description / suggestion
✅ Precise location: all findings reference a specific file:line or @@ block
✅ bug fix verification: a bug fix diff must verify the correctness of the fix and flag any remaining or partial issues

Scope Boundaries

This skill is responsible for：

current git diff (staged + unstaged)
untracked files in the changeset (included by default, treated as a complete file add)
5-dimension analysis: intent / impact, regression / correctness, breaking / compatibility, side effects / idempotency, observability

This skill is not responsible for：

repository-level or snapshot-level review → review-codebase
full-dimension orchestrated review → orchestrate-code-review
architecture / security / performance / testing cognitive dimensions → corresponding cognitive atomic skills
language / framework-specific conventions → corresponding atomic skills

Handoff point: after findings are output, they serve as the scope-step aggregation input for orchestrate-code-review; or hand off to orchestrate-repair-loop for fix iteration.

Use cases

pre-commit / pre-PR gate: quickly check for issues introduced by changes before committing
As the scope step of orchestrate-code-review: choose one of review-codebase Choose one of two
Focused review: the user explicitly says "only look at changes"

Behavior

Scope resolution

Analysis target: files in the changeset—diff (staged + unstaged) + untracked files included by default
Untracked file handling: the caller passes in the path and full content; treat as a complete file add, apply the same 5-dimension checklist; reference file:line
Do not analyze: files that are unchanged or outside the changeset

5-dimension analysis checklist

For each changed file, produce findings along the following dimensions:

Intent and impact: what changed and why; impact on callers / data / configuration / deployment
Regression and correctness: whether new bugs are introduced or edge cases are missed; whether a bug fix diff is complete
breaking change and compatibility: whether it breaks API / data / configuration contracts; backward compatibility; versioning / deprecation
Side effects and idempotency: unintended side effects, data corruption, repeated execution risk, idempotency issues
Observability: whether the change adds / fixes logs, metrics, and error messages used for production debugging

Special cases

bug fix diff: verify the correctness of the fix, record any remaining or partial issues
Formatting / comment-only diff: output one minor finding "formatting / comments only, no behavior change"; if comments contradict the code, emit a finding containing a suggestion

Input and output

Input

git diff: staged + unstaged changes of the current branch vs HEAD
Untracked files(included by default): path + full content

Output

Findings list: standard format (location / category=scope / severity / title / description / suggestion）
Each finding must include a file:line or @@ block reference
Each finding must include an actionable suggestion (fix direction + specific location)

Restrictions

Hard boundaries

Do not review files outside the diff
Do not output findings without a file:line reference
Do not use vague language ("there may be a problem" without type and direction → delete)
Do not perform security / architecture / language / framework checks (stay within the scope dimension)

Skill boundaries

Do not do(handled by other atomic skills):

Repository-level / snapshot-level review → review-codebase
Full-dimension orchestration → orchestrate-code-review
Security → review-security
Architecture → review-architecture
Language / framework → corresponding atomic skill

Self-check

Review only the change set (diff + included untracked files)
Full coverage of all 5 dimensions
Each finding is format-compliant (contains 6 fields)
Each finding includes a file:line or @@ block reference
Each finding includes an actionable suggestion
bug fix diff has verified fix correctness

Examples

Example 1: API change

Input: diff adds query parameters and modifies response shape
Expected: findings cover intent / impact (on callers), backward compatibility risk, breaking change suggestions (such as versioning or deprecation); cite specific lines or @@ blocks; do not output security / architecture findings (hand off to the corresponding atomic skills)

Example 2: bug fix

Input: diff fixes null pointer and error codes
Expected: findings confirm the fix + verify whether similar null pointer / error code issues still exist; observability dimension (logs / errors); cite changed lines; category=scope

Example 3: formatting / comments only

Input: diff contains only indentation / whitespace / comment changes
Expected: either no finding, or one minor finding "formatting / comments only, no behavior change"; if comments contradict the code, emit a finding containing a suggestion

Example 4: new (untracked) files in the change set

Input: diff + untracked files (path + full content)
Expected: new files are reviewed as full-file adds; apply the 5-dimension checklist; location=path and line references; category=scope