ai-for-dummies/public/submitted-skills/Leonardo Morales/skills/semantic-diff-review/SKILL.md

name, description

name

description

semantic-diff-review

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:

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

   Latest commit (HEAD):

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

   Specific commit hash or revision:

   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:

   {
     "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:

   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.