leszekgruchala/buddy / skills/change-report
change-report
VerifiedValidate a PR or branch diff and create an HTML change report or walkthrough with before/after behavior, practical impact, and material architecture changes. Keep the current request in this skill; route new requests by their own scope.
Change Report
Keep the current request in this skill. Do not activate another Buddy skill without user or develop direction. Workers return to their caller. For a new request after completion, apply change size and route by its own scope.
Resolve .ai/ paths from the user's workspace root (its git root), never from the skill or plugin directory.
Create the shortest HTML explanation of what changed, why, who is affected, and expected consequences or required actions. Include fixes, UX, maintenance, documentation, and tests without requiring architecture changes. The diff and both code versions establish behavior; specs and PR descriptions establish intent. Validate reported changes, not merge readiness or deployment status.
Model selection
Apply model selection; recommend balanced.
Establish the comparison
- Read repository instructions and inspect the working tree. Resolve the repository, target, and base for the requested PR, branch, or explicit local changes before writing. Ask one concise question if ambiguous; never silently select
mainor include unrelated edits. - For a PR, use read-only
ghcommands when available to obtain base/head revisions, description, file list, and patch. Use recorded change revisions for merged PRs, never the current base tip. For a branch, resolve base/head commits and use their merge base as before. Inspect revisions without switching branches; record base, merge base, and head in source labels/evidence. - For requested uncommitted work, use the agreed base, distinguish staged/unstaged changes, and explicitly include relevant untracked files. Capture status and content fingerprints for rechecking; label a working-tree snapshot rather than a committed head. Disclose excluded, unavailable, binary, or truncated material when it limits the explanation.
- Read every changed file and available related spec/worklog. Trace affected entry points, callers, contracts, state, outputs, registrations, configuration, tests, and failure paths through relevant unchanged code. Group by observable feature/process, not filename.
Validate the explanation
- Check patch whitespace and each before/after claim against its revision, including material architecture connections. Cite every change; warn with the affected feature and gap when evidence is unavailable. Separate confirmed behavior, inferred purpose, and unknowns; never invent old behavior or claim unmeasured improvements.
- Run focused documented checks in non-writing modes where available. Another checkout/revision is not target evidence. Never install dependencies, modify product files, rewrite snapshots, deploy, or fix defects. Record checks as passed, failed, or not run with short reasons; label CI evidence with its revision.
- Show confirmed defects, specification mismatches, and material evidence gaps as warnings before the comparison. Passing checks do not prove correctness. Recheck revisions and local fingerprints after analysis; if changed, mark the report incomplete and do not present it as current.
Highlight changes that need attention
Assess each feature for diff-, caller-, or contract-supported markers; file count alone does not establish risk. Each marker needs a short reason, specific action, and evidence on its comparison row.
| Marker | Use when | State the next action |
|---|---|---|
| High risk | A concrete failure in changed core behavior could affect security, persistent data, payments, or a critical shared process. | Name the failure path and the targeted check or owner review that addresses it. |
| Breaking change | Existing callers, stored data, configuration, or workflows cannot use the new contract without adaptation. | Name what breaks and the required migration or caller update. |
| Human review | Domain judgment, a critical architecture/trust boundary, or a meaningful user journey needs a person to check it beyond the available automated evidence. | Name the decision or invariant to review, or the smallest hands-on scenario and its expected result. |
Several markers may apply; combine code and hands-on checks under Human review. Separate confirmed breaks from uncertain compatibility, which belongs in a warning or review action. Do not imply review occurred without evidence or invent an approval requirement. Passing tests do not remove supported markers; omit inapplicable ones.
Keep it short
Explain each change once through purpose and Before / After / Impact rows. State practical consequences, meaningful conditions, limits, and required actions; avoid generic benefits, invented actions, commit logs, file inventories, implementation narration, and repeated summaries. Architecture belongs only when material. For maintenance, docs, or tests, state the supported developer outcome and whether runtime behavior changes. Read outcome examples when architecture is unchanged or impact is unclear.
| Change | Reading budget | Diagram choice |
|---|---|---|
| Small or mechanical | Aim for at most 200 visible words and 1–3 rows | Omit diagrams when the table explains the change. |
| One meaningful process change | Aim for at most 450 visible words and 3–6 rows | Add Before/After diagram tabs when execution flow or wiring changes. |
| Several interacting changes | Aim for at most 700 visible words and 4–8 grouped rows | Show the main affected flow in Before/After tabs; collapse secondary evidence. |
These are ceilings, not quotas; scale by behavioral complexity, not diff size. Preserve material failures and uncertainty even above the budget.
Before authoring diagram data or rendering, read the report data contract for exact fields, limits, diagram rules, and interaction behavior.
Save and render
- Reuse the supplied related worklog, otherwise a clear content/name match tied to the feature, PR, or branch in the target repository's
.ai/worklog/. If absent, create.ai/worklog/<yyyyMMdd>_<work-name>/using the user's local date. Resolve.aisymlinks without altering them; never save in the installed skill directory. If repository writes are blocked, report the blocker rather than switch repositories. - Save and update the same
change-report_<work-name>.htmlfor related follow-ups. Preserve other diary files. Put inputs in the worklog'strash/unless repository instructions give another temporary location. - Write evidence-backed JSON and run the renderer with input/output paths. Use the fixed template without changing layout, section order, palette, or typography. Use
--overwriteonly for this workflow's existing report. - Open locally when possible. Verify outcome, audience, actions, uncertainty, warnings before comparisons, and labeled Before/After/Impact fields with readable attention actions and no horizontal scrolling on narrow screens. Check labels/arrows, distinct change states, inspector connections, and mouse/keyboard tabs and selections against the data contract.
- Require one offline, self-contained file: no CDN, external fonts/scripts, or remote renderer. Use only the bundled interaction script; never insert report content into its code, or raw PR text, code, credentials, or arbitrary HTML/SVG into the template. Redact sensitive evidence.
- Return the report link and one sentence about the outcome or material validation gap. Do not duplicate the report in chat or upload, post, or publish without an explicit request.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |