visual-change-recap

Visual Change Recap

Explain what a body of code changes actually introduced at a higher altitude than line-by-line review. The repository and diff are the source of truth; the HTML recap is a grounded human-facing projection.

The skill is local-only. Do not use MCPs, hosted plan services, GitHub Actions, or external assets. It explains a change but does not certify correctness, security, or conformance with a specification.

Inputs

Accept a pull request, branch, commit range, or working tree. Prefer an explicit base when the user gives one. Otherwise resolve the default branch locally and record the chosen merge base. An original implementation plan is optional and may be used only to show planned-versus-delivered status; it must never override evidence from the code.

This offline skill cannot resolve an arbitrary PR number or URL from a remote host. For a PR, use already-fetched local refs or require the caller to provide the local base and head refs. Do not add network access merely to resolve it.

Workflow

1. Establish the exact base, head, and whether uncommitted changes belong in scope. Exclude unrelated pre-existing work.

2. Create a fresh temporary directory outside the repository unless the user supplies an output directory. Collect deterministic metadata using absolute script and output paths:

   python3 /absolute/skill/directory/scripts/collect_diff.py \
     --repo /absolute/repository \
     --output /absolute/output/directory/context.json
   

   Pass --base <ref> or --include-working-tree when appropriate.

3. Read the changed files and diff once, grouping them by behavior rather than directory or alphabetical order. Identify the outcome, public/data contracts, runtime flows, UI states, deployment effects, observed validation, and load-bearing files. For a very large diff, state what was omitted instead of pretending to have represented everything.

4. Make the default view a reviewer briefing, not a complete dossier. Expand no more than three primary visual blocks: normally the current capability map, one architecture view, and one runtime or data-model view. Keep the concise review-focus bullets visible in the overview; detailed review questions may be collapsed. Endpoint operation rows may remain visible when compact, or the whole reference may be collapsed for a very large surface. Collapse tool catalogs, secondary diagrams, UI states, code excerpts, plan comparison, files, and exhaustive evidence.

5. Read references/visual-document.md and references/language-style.md. Author a v5 document.json with kind: "recap", durable base/head provenance, and attach file/line/ref evidence to every nontrivial claim. Inference must be visibly labeled. Never copy secret values into the JSON; replace them before rendering. Describe the branch with new, changed, reused, and removed. Do not use plan-conformance language outside the collapsed alignment block.

6. Check the human-facing prose before rendering: