Marcos Silva
96 lines
5.2 KiB
Markdown
96 lines
5.2 KiB
Markdown
---
|
|
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.
|