feat: review semantic diff submission

2026-09-04 14:06:50 -03:00
parent 9557957698
commit d12d301a1a
8 changed files with 1430 additions and 2 deletions
@@ -0,0 +1,95 @@
+---
+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.