Git Diff Review Skill

Commands

$ARGUMENTS

review

/interactive-diff-review [target]

--verify

/interactive-diff-review --verify

--apply

/interactive-diff-review --apply

--commit

/interactive-diff-review --commit

--verify

<commit>

<commit_a> <commit_b>

/interactive-diff-review --apply --commit

Command Routing

1. Parse

   $ARGUMENTS

   — extract command flags and remaining positional args (diff target).
2. If no command flag is present → default to

   review

   .
3. Route to the corresponding section below.

Workflow Checklist

Diff Review Progress:
- [ ] Step 1: Resolve & Parse
  - [ ] 1.1 Run resolve_diff.py to get diff + language
  - [ ] 1.2 Verify no error, inform user of diff source + language
  - [ ] 1.3 Run parse_hunks.py to split into hunks
  - [ ] 1.4 Handle edge cases ⚠️ Load references/edge-cases.md
- [ ] Step 2: Interactive Review ⚠️ CORE LOOP
  - [ ] Load references/review-format.md
  - [ ] 2.1 Display hunk (index/total, file, type, diff body)
  - [ ] 2.2 Provide analysis (summary, impact, risks, suggestions)
  - [ ] 2.3 Collect decision via ask_user_input (Accept / Reject / Skip)
  - [ ] 2.4 If rejected, ask reason (open-ended text follow-up)
  - [ ] 2.5 Show running tally, advance to next hunk
  - [ ] 2.6 Repeat 2.1–2.5 until all hunks done
  - [ ] 2.7 Loop back for any skipped hunks
- [ ] Step 3: Coverage Verification ⚠️ REQUIRED
  - [ ] 3.1 Re-run resolve_diff.py + parse_hunks.py
  - [ ] 3.2 Compare new hunks against reviewed hunks (file + header + body)
  - [ ] 3.3 If new/changed hunks → review them (back to Step 2)
  - [ ] 3.4 Confirm full coverage before proceeding
- [ ] Step 4: Generate Report
  - [ ] Load references/report-template.md
  - [ ] 4.1 Build Markdown report (detected language, diff order)
  - [ ] 4.2 Save to /mnt/user-data/outputs/diff-review-report.md
  - [ ] 4.3 Present to user

Step 1: Resolve & Parse

1.1 Run resolver

python scripts/resolve_diff.py                       # auto: staged → workspace
python scripts/resolve_diff.py <commit>              # single commit
python scripts/resolve_diff.py <commit_a> <commit_b> # commit range

{ source, ref, language, diff, error }

1.2 Verify & inform

error

1.3 Save diff & run parser

diff

# Write the diff field to a temp file (agent should use Write tool or shell redirect)
# e.g. write resolve output's .diff value to /tmp/diff.txt

python scripts/parse_hunks.py --file /tmp/diff.txt

{ total, hunks: [{ index, file, header, body, type, status, reason }] }

1.4 Edge cases

references/edge-cases.md

Step 2: Interactive Review

references/review-format.md

Step 3: Coverage Verification

1. Re-run

   resolve_diff.py

   +

   parse_hunks.py

   with same arguments as Step 1.
2. Compare new hunks against reviewed hunks by

   file + header + body

   .
3. New/changed hunks found → go back to Step 2 for those hunks only.
4. Confirm full coverage. Only proceed to Step 4 when all hunks are decided.

Step 4: Generate Report

references/report-template.md

diff-review-report.md

Command:

--verify

1. Check

   diff-review-report.md

   exists in project root. If not → error: "No report found. Run

   review

   first."
2. Re-run

   resolve_diff.py

   +

   parse_hunks.py

   with same target args to get current hunks.
3. Parse the report's Overview table to extract reviewed hunks (file + type + status).
4. Compare:
   • Every current hunk has a matching entry in the report (by file path + hunk header + body hash).
   • No extra entries in report that don't exist in current diff (stale entries).
5. Check that all hunks have status ✅ Accepted (no ❌ Rejected, no missing).
6. Output result:
   • PASS: "Verification passed. All N hunks reviewed and accepted. Ready to commit."
   • FAIL — unreviewed hunks: List the unmatched hunks.
   • FAIL — rejected hunks: List the rejected hunks with their reasons.
   • FAIL — stale report: Report doesn't match current diff. Suggest re-running

     review

     .

Command:

--apply

1. Check

   diff-review-report.md

   exists. If not → error.
2. Parse the report to find all ❌ Rejected hunks and their rejection reasons + analysis suggestions.
3. For each rejected hunk (in diff order): a. Read the relevant file and locate the code region from the hunk. b. Based on the rejection reason and the review analysis, generate a fix. c. Apply the fix using Edit tool. d. Show the user what was changed and why.
4. After all fixes applied, inform the user:
   • "Applied fixes for N rejected hunks. Run

     --verify

     or re-run

     review

     to confirm."

--apply

review

--verify

Command:

--commit

1. Run the

   --verify

   flow internally (same as above).
2. If verify FAILS → stop and show the failure reason. Do not commit.
3. If verify PASSES: a. Parse the report to build a commit message:
   • Subject line: summarize the changes (max 72 chars), in detected language.
   • Body: list the key changes from the report overview (accepted hunks grouped by file). b. Show the proposed commit message to the user for confirmation. c. On user approval:

   • git add -A

     (or stage the specific files from the review).

   • git commit

     with the message. d. Show the commit result.

Parameter Reference

review

<commit>

<commit_a> <commit_b>

--verify

--apply

--commit

Language

• Detected from

  git log --oneline -10

  by

  resolve_diff.py

  .
• All UI, analysis, and report use detected language; technical terms stay English.
• Mixed-language commits → most frequent wins.
• No history → fall back to user's conversation language.

File Structure

git-diff-review/
├── SKILL.md                          # This file — workflow orchestration
├── scripts/
│   ├── resolve_diff.py               # Diff source + language detection
│   └── parse_hunks.py                # Unified diff → structured hunks
└── references/
    ├── review-format.md              # Step 2: display, analysis, decisions
    ├── report-template.md            # Step 4: Markdown report template
    └── edge-cases.md                 # Step 1.4: edge case handling