bdv-change-report

name

bdv-change-report

description

Use ONLY when the user explicitly asks for it — e.g. "give me the change report," "summarize the changes," "what did you change," "/change-report," or similar direct requests. Produces a short, high-level report (not a line-by-line walkthrough) covering what changed, behavior differences, assumptions made, known gaps, risk areas, and what to verify manually — so the user can review quickly without reading the whole diff. Do NOT trigger this automatically after writing or editing code — wait for the user to ask.

Change Report

Your job here is to compress a code change into something a busy human can review in under a minute, without hiding anything that matters. Optimize for the reader's limited attention, not for making the change look complete.

When this runs

Only when the user explicitly asks for it. Do not run this automatically after finishing a coding task — wait to be asked, even if the change was large. If you're not fully certain what changed by the time you're asked (e.g. some time or turns have passed), run git status and git diff (and git diff --staged) first to ground the report in the actual current diff rather than relying on memory.

Output format

Use these exact headings. Bullets, not paragraphs. No code snippets inside the report — the diff already has the detail; this is for understanding.

Summary

1–3 sentences, plain language: what changed and why. Avoid implementation jargon and code identifiers where possible.

Files touched

Group by purpose/module, not a flat list. e.g. Auth: login.ts, session.ts · Tests: login.test.ts

Behavior diff

For each meaningful change: Before: X → After: Y, focused on observable behavior, not code structure. If this was a pure refactor with no behavior change, say that explicitly — it's a useful signal on its own.

Assumptions made

Anything inferred because the request was ambiguous or underspecified, or any judgment call made along the way. Name the assumption and why you chose it. If none, say so.

Known gaps / not done

Anything skipped, deferred, stubbed, partially implemented, or left as a TODO in code. Anything explicitly out of scope. Only say "nothing" if that's true.

Risk flags

Tag each: 🔴 must-check / 🟡 worth a look / ⚪ minor.

Always flag if touched: auth/permissions, payments/billing, data deletion/migration, concurrency/race conditions, external API calls, error handling paths, or anything you're not fully confident is correct.

If you did not actually trace an edge case (empty input, null, concurrent calls, network failure, retries), say so directly rather than staying silent about it.

What to verify manually

The 2–5 highest-value things to check first, ordered by importance. Think like a reviewer with two minutes: "start here." This is the most important section — it's what directs the human's limited attention to what matters.

Hard rules

• Never write "robust," "production-ready," "clean," or "handles all edge cases" without stating exactly what was checked to justify it.
• If you built on or modified logic you don't fully understand — inherited code, an unfamiliar pattern, unclear intent — say so plainly instead of presenting it with confidence you don't have.
• Prefer "I'm not certain X handles Y" over silence or false confidence.
• The report must reflect what you actually did and verified, not what a typical/ideal solution to this task would look like.
• If truly nothing risky or noteworthy happened (e.g. a one-line typo fix), keep the report to 2–3 lines total — don't pad it to look thorough.