---
name: semantic-diff-review
description: Inspect staged, unstaged, and untracked Git changes or the diff introduced by the latest or a specified commit; assign deterministic IDs to individual diff hunks; semantically group hunks by purpose; and generate a self-contained dark HTML review dashboard. Use when asked to review, organize, explain, or split local changes or a commit into semantic units without staging, reverting, committing, checking out revisions, or otherwise changing Git state.
---

# Semantic Diff Review

Create `.semantic-review/review.html` from real Git output. Review either current Git changes or one commit against its first parent. Keep Codex responsible only for semantic classification; delegate collection, validation, and HTML generation to the bundled deterministic Python scripts.

## Safety boundary

- Never run commands that change Git state, including `git add`, `git restore`, `git checkout`, `git reset`, `git commit`, `git stash`, `git clean`, `git update-index`, or temporary worktree/branch manipulation.
- Never hand-author, reconstruct, shorten, or correct patch text.
- Never generate HTML, CSS, or JavaScript during a review. Use `scripts/render_review.py` unchanged.
- Write only `.semantic-review/classification.json`; the collector writes `changes.json` and the renderer writes `review.html`.
- Treat `.semantic-review/changes.json` as immutable Git-derived evidence. Re-run the collector instead of editing it.

## Workflow

Set `SKILL_DIR` to this skill's directory and run every command from anywhere inside the target repository.

1. Choose exactly one review target and collect it:

   Current staged, unstaged, and untracked changes:

   ```bash
   python3 "$SKILL_DIR/scripts/collect_changes.py" --repo .
   ```

   Latest commit (`HEAD`):

   ```bash
   python3 "$SKILL_DIR/scripts/collect_changes.py" --repo . --commit
   ```

   Specific commit hash or revision:

   ```bash
   python3 "$SKILL_DIR/scripts/collect_changes.py" --repo . --commit <revision>
   ```

   Use commit mode whenever the user asks for the latest commit, a commit hash, or a named revision. The collector resolves the revision to a commit and diffs it against its first parent; for a root commit it uses Git's empty tree. Commit mode ignores working-tree changes. Never check out, reset, stage, or otherwise expose a commit through working-tree mutation.

   The collector finds the repository root, excludes `.semantic-review/`, assigns stable content-derived hunk IDs, and writes `.semantic-review/changes.json`. It uses only read-only Git commands and preserves patches directly from Git output.

2. Read `.semantic-review/changes.json`. Semantically classify every entry in `hunks` exactly once. Base grouping on intent and purpose, not merely file proximity. Keep separable concerns in separate groups; keep tests, docs, migrations, and configuration with the implementation they directly support when they form one coherent change.

3. Write `.semantic-review/classification.json` with exactly this shape:

   ```json
   {
     "schema_version": 1,
     "groups": [
       {
         "title": "Concise semantic group title",
         "purpose": "What this change accomplishes and why",
         "risk": {
           "level": "low",
           "rationale": "Concrete failure modes or reasons risk is limited"
         },
         "review_points": [
           "A specific behavior, edge case, or integration to verify"
         ],
         "suggested_commit_message": "type(scope): concise imperative subject",
         "hunk_ids": ["H-0123456789ABCDEF"]
       }
     ]
   }
   ```

   Use only `low`, `medium`, or `high` for `risk.level`. Use `groups: []` when `hunks` is empty. Do not add patch, diff, source, code, HTML, CSS, or JavaScript fields. Do not copy source lines into semantic prose.

4. Render and validate the review:

   ```bash
   python3 "$SKILL_DIR/scripts/render_review.py" \
     --changes .semantic-review/changes.json \
     --classification .semantic-review/classification.json \
     --output .semantic-review/review.html
   ```

   If validation reports missing, duplicate, or unknown hunk IDs, fix only `classification.json` and render again. If it reports changed or invalid collected evidence, re-run collection and classification.

5. Report the reviewed target, absolute path to `.semantic-review/review.html`, the number of semantic groups and hunks, and that Git state was left untouched. Do not open a browser unless the user asks.

## Classification guidance

- Describe purpose at the behavioral or architectural level.
- Assess risk from observable failure modes, compatibility, data handling, security boundaries, concurrency, migrations, and test coverage.
- Make review points actionable questions or checks rather than generic advice.
- Suggest one commit message per semantic group. Do not claim a commit was created.
- Prefer a small number of coherent groups, but never force unrelated hunks together.
- Preserve the collector's hunk IDs verbatim. They are the only link between semantic judgments and source patches.

The renderer rejects incomplete classifications and obtains every displayed patch exclusively from `changes.json`; model-authored text is inserted only as escaped semantic metadata.