Change report
Understand a code change and its impact
Readers can see what changes, who is affected, and which actions matter in one concise report. Diagrams explain the wiring when it helps.
Local skill addition · tracked edits and new skill files · candidate code · 9f70e9307bbf23d13c2db198379c54bdc101f928 → Working tree · snapshot recorded in evidence
Before → After
| Feature | Before | After | Impact |
|---|---|---|---|
| Change walkthrough | Buddy has no dedicated HTML change-report skill. | A saved report explains affected behavior, its purpose, and practical consequences. | Reviewers can understand the change and return to its evidence without reading the whole diff. |
| Visual explanation Human review | There is no fixed change-report layout or diagram renderer. | Readers can compare behaviors and follow changed connections in text or selectable diagrams. | Reviewers can understand the main flow without selecting every component.
|
| Length and evidence | No dedicated change-report contract sets the reading budget. | Small changes use brief rows; extra details and source references stay collapsed or optional. | Readers can scan the outcome and check supporting evidence when needed. |
| Review attention Human review | No structured markers identify risk or recommended human checks. | Rows identify risks, breaking contracts, and review actions; warnings appear before the comparison. | Reviewers see migrations, focused checks, and evidence gaps before treating the report as complete.
|
| Worklog continuity | Research and specification skills already use related worklogs. | The report reuses a matching diary or creates one and updates the same HTML file. | Keeps the explanation beside the change's existing project context. |
Architecture
Added connections
- PR or branch changes → Change analysis: Reads the frozen diff and the corresponding source versions.
- Change analysis → Report renderer: Provides structured facts, diagram connections, and validation results.
- Report renderer → Worklog report: Writes a self-contained HTML file into the related worklog.
Unchanged connections
- PR or branch changes → Code review: The reviewer receives the requested code change.
- Code review → Findings in chat: The reviewer returns actionable findings in chat.
Before
Scroll horizontally if needed to see the full diagram.
After
Scroll horizontally if needed to see the full diagram.
NewChangedRemovedUnchanged
PR or branch changes
UnchangedIdentify the exact change to explain.
- Before
- Review reads the requested local change.
- After
- Review and reporting each use a defined comparison target.
Before connections
Incoming
No incoming connections shown in this diagram.
Outgoing
- Code reviewReview targetThe reviewer receives the requested code change.
Evidence (2)
- skills/review-code/SKILL.md: Establish the target and contract
- skills/change-report/SKILL.md: Establish the comparison
Code review
UnchangedFind evidence-backed defects in a requested change.
- Before
- An independent reviewer investigates the code and its affected contracts.
- After
- The existing review workflow continues alongside the new report workflow.
Before connections
Incoming
- PR or branch changesReview targetThe reviewer receives the requested code change.
Outgoing
- Findings in chatDefectsThe reviewer returns actionable findings in chat.
Evidence (1)
- skills/review-code/SKILL.md
Findings in chat
UnchangedReturn actionable review findings to the caller.
- Before
- Review returns its findings in chat.
- After
- Review still returns findings in chat; the HTML report is a separate artifact.
Before connections
Incoming
- Code reviewDefectsThe reviewer returns actionable findings in chat.
Outgoing
No outgoing connections shown in this diagram.
Evidence (1)
- skills/review-code/SKILL.md: Return to the caller
PR or branch changes
UnchangedIdentify the exact change to explain.
- Before
- Review reads the requested local change.
- After
- Review and reporting each use a defined comparison target.
After connections
Incoming
No incoming connections shown in this diagram.
Outgoing
- Code reviewReview targetThe reviewer receives the requested code change.
- Change analysisReport requestReads the frozen diff and the corresponding source versions.
Evidence (2)
- skills/review-code/SKILL.md: Establish the target and contract
- skills/change-report/SKILL.md: Establish the comparison
Code review
UnchangedFind evidence-backed defects in a requested change.
- Before
- An independent reviewer investigates the code and its affected contracts.
- After
- The existing review workflow continues alongside the new report workflow.
After connections
Incoming
- PR or branch changesReview targetThe reviewer receives the requested code change.
Outgoing
- Findings in chatDefectsThe reviewer returns actionable findings in chat.
Evidence (1)
- skills/review-code/SKILL.md
Findings in chat
UnchangedReturn actionable review findings to the caller.
- Before
- Review returns its findings in chat.
- After
- Review still returns findings in chat; the HTML report is a separate artifact.
After connections
Incoming
- Code reviewDefectsThe reviewer returns actionable findings in chat.
Outgoing
No outgoing connections shown in this diagram.
Evidence (1)
- skills/review-code/SKILL.md: Return to the caller
Change analysis
NewExplain the implemented behavior and its architectural effect.
- Before
- Buddy has no dedicated HTML change-report skill.
- After
- The new skill traces both revisions, validates claims, and prepares concise report data.
After connections
Incoming
- PR or branch changesReport requestReads the frozen diff and the corresponding source versions.
Outgoing
- Report rendererReport dataProvides structured facts, diagram connections, and validation results.
Evidence (1)
- skills/change-report/SKILL.md: Validate the explanation
Report renderer
NewCreate a consistent offline HTML report from validated input.
- Before
- This workflow has no bundled report renderer.
- After
- The renderer offers readable execution flow alongside selectable diagrams and detailed inspection.
After connections
Incoming
- Change analysisReport dataProvides structured facts, diagram connections, and validation results.
Outgoing
- Worklog reportHTMLWrites a self-contained HTML file into the related worklog.
Attention
Visual explanation
- Human review: Each component's story must agree with the diagram and code.Select components and switch tabs; confirm responsibilities and connections match both versions.
Review attention
- Human review: Report text comes from untrusted diffs and descriptions.Review escaping and confirm report data never enters the tab script.
Evidence (5)
- skills/change-report/scripts/render_report.py
- skills/change-report/assets/report.html
- skills/change-report/assets/report.html: tab panels
- skills/change-report/scripts/render_report.py: _text
- skills/change-report/assets/report.html: bundled script
Worklog report
NewKeep the explanation beside the change's project context.
- Before
- Research and specifications already live in worklog diaries.
- After
- The HTML report reuses a related diary and stays in the same file for follow-ups.
After connections
Incoming
- Report rendererHTMLWrites a self-contained HTML file into the related worklog.
Outgoing
No outgoing connections shown in this diagram.
Evidence (1)
- skills/change-report/SKILL.md: Save and render
Validation
- passedPackage definitionsAgent Skills, Codex, Claude Code, Cursor, and whitespace checks passed.
- passedRenderer regressionsFive tests cover named evidence gaps, escaping, legacy inputs, mobile labels, and connection order.
- passedReader checksWarnings appear first; all comparison fields fit mobile screens. Tabs, selection, print, and offline checks passed.
- not runPaired evaluationsFive scenarios are defined and checked; candidate-versus-baseline model runs have not been executed.
Evidence · 13 references
- Change walkthroughskills/change-report/SKILL.md:9
- Change walkthroughREADME.md:297
- Visual explanation · Human reviewskills/change-report/assets/report.html: tab panels
- Visual explanationskills/change-report/assets/report.html
- Visual explanationskills/change-report/scripts/render_report.py
- Visual explanationSnapshot includes the skill, renderer/template, validation integration, regression tests, and evaluation fixtures. SHA-256 of sorted path, NUL, and file-content pairs: b28a5e3d15d49e9b9fcb7ab133c1b1dfbe0c8bf027dc076b4d13b45662337232
- Length and evidenceskills/change-report/SKILL.md: Keep it short
- Length and evidenceskills/change-report/references/report-data.md
- Review attention · Human reviewskills/change-report/scripts/render_report.py: _text
- Review attention · Human reviewskills/change-report/assets/report.html: bundled script
- Review attentionskills/change-report/SKILL.md: Highlight changes that need attention
- Review attentionskills/change-report/scripts/render_report.py: ATTENTION
- Worklog continuityskills/change-report/SKILL.md: Save and render