Visual diff review
Contract
| Field |
Bound contract |
| Trigger |
Diff review of a branch, commit, range, PR, or working tree against main or master by default |
| Authority |
Reversible local: writes only named local artifacts; rollback is undo. No remote mutation. State the rollback path before mutation. |
| Side effect |
Writes the 7-section review page to the diagrams directory; opens it |
| Done |
Scope, before/after behavior, risk, coupling, and a merge recommendation all cited from evidence |
Inputs
The diff target must be supplied: a branch name, commit hash or range, PR identifier, or working tree. The comparison base defaults to main; supply a named base only when it differs. The source is the live git diff of the named target against the named or default base.
Procedure
- Collect. Resolve the diff target to the named comparison base. Extract the full diff. Done when: the full diff is extracted against the named base.
- Scope. Enumerate every file and component affected. Classify the change surface. Done when: every affected file and component is enumerated and classified.
- Before/After. Describe the behavior before and after each hunk. Capture the delta in concrete terms. Done when: every hunk has a before/after behavioral description.
- Risk. Assess each risk dimension: correctness, performance, security, and compatibility. Cite evidence from the diff. Done when: every risk dimension is assessed with cited evidence.
- Coupling. Identify cross-component dependencies and side-effect surfaces within the diff. Done when: every cross-component dependency and side-effect surface is identified.
- Merge recommendation. State merge, defer, or reject with the specific evidence from steps 2–5. Done when: a merge recommendation is stated with cited evidence.
- Render. Write the 7-section review page to
diagrams/visual-diff-review.html. Open it. Done when: the page is written and opened, or the path is reported.
Failure and recovery
- Unresolvable diff target. Report the exact name that failed and stop. Do not widen scope.
- Empty diff. Report that no changes were found and stop. The done predicate does not hold.
- Unavailable external reference. Mark the affected section as
INSUFFICIENT EVIDENCE and continue. Do not fabricate citations.
- Filesystem error on write. Report the error and stop. Roll back any partial file. Do not proceed to open.
Partial results are acceptable only when each incomplete section is explicitly labeled. Silence is not a partial result.
Output
A self-contained diagrams/visual-diff-review.html with seven sections in order: Overview, Before State, After State, Risk Assessment, Coupling Analysis, Merge Recommendation, Evidence Log: every section citing evidence or marked INSUFFICIENT EVIDENCE.
1---2name: visual-diff-review3description: Use when asked to review a diff and produce a 7-section visual page. Not for interactive review walks or PR-specific review: use show-review.4---56# Visual diff review78## Contract910| Field | Bound contract |11|---|---|12| Trigger | Diff review of a branch, commit, range, PR, or working tree against main or master by default |13| Authority | Reversible local: writes only named local artifacts; rollback is undo. No remote mutation. State the rollback path before mutation. |14| Side effect | Writes the 7-section review page to the diagrams directory; opens it |15| Done | Scope, before/after behavior, risk, coupling, and a merge recommendation all cited from evidence |1617## Inputs1819The diff target must be supplied: a branch name, commit hash or range, PR identifier, or working tree. The comparison base defaults to `main`; supply a named base only when it differs. The source is the live git diff of the named target against the named or default base.2021## Procedure22231. **Collect.** Resolve the diff target to the named comparison base. Extract the full diff. **Done when:** the full diff is extracted against the named base.242. **Scope.** Enumerate every file and component affected. Classify the change surface. **Done when:** every affected file and component is enumerated and classified.253. **Before/After.** Describe the behavior before and after each hunk. Capture the delta in concrete terms. **Done when:** every hunk has a before/after behavioral description.264. **Risk.** Assess each risk dimension: correctness, performance, security, and compatibility. Cite evidence from the diff. **Done when:** every risk dimension is assessed with cited evidence.275. **Coupling.** Identify cross-component dependencies and side-effect surfaces within the diff. **Done when:** every cross-component dependency and side-effect surface is identified.286. **Merge recommendation.** State merge, defer, or reject with the specific evidence from steps 2–5. **Done when:** a merge recommendation is stated with cited evidence.297. **Render.** Write the 7-section review page to `diagrams/visual-diff-review.html`. Open it. **Done when:** the page is written and opened, or the path is reported.3031## Failure and recovery32- **Unresolvable diff target.** Report the exact name that failed and stop. Do not widen scope.33- **Empty diff.** Report that no changes were found and stop. The done predicate does not hold.34- **Unavailable external reference.** Mark the affected section as `INSUFFICIENT EVIDENCE` and continue. Do not fabricate citations.35- **Filesystem error on write.** Report the error and stop. Roll back any partial file. Do not proceed to open.3637Partial results are acceptable only when each incomplete section is explicitly labeled. Silence is not a partial result.3839## Output40A self-contained `diagrams/visual-diff-review.html` with seven sections in order: Overview, Before State, After State, Risk Assessment, Coupling Analysis, Merge Recommendation, Evidence Log: every section citing evidence or marked `INSUFFICIENT EVIDENCE`.
OutlineDriven