explain-diff

Name: explain-diff
Author: minghinmatthewlam

34stars4forks

How to install explain-diff?

minghinmatthewlam/agent-guards/explain-diff

$npx -y skills add minghinmatthewlam/agent-guards --skill explain-diff

Installs into the current project.

Summary

Create a focused self-contained HTML explanation of a code change, diff, branch, commit, PR, or worker implementation. Use when the user asks to understand code changes, needs an important implementation kept visible as a learning or handoff artifact, or when an orchestrator/work

Files · 1

View on GitHub

SKILL.md

1	# Explain Diff
2
3	Read and follow `../explain-report/SKILL.md`, then apply the code-change requirements below using Change mode.
4
5	Create a focused, readable HTML explanation of the specified code change. The report should help the user understand the surrounding subsystem and retain the important implementation knowledge, not merely inventory modified files.
6
7	This skill is for human understanding, not verification. Do not replace tests, screenshots, videos, logs, or other proof artifacts. If proof artifacts exist, link to them from the explanation.
8
9	## Change-Mode Sections
10
11	Include:
12
13	- Background: Explain the existing system needed to understand the change. Explore surrounding code, not just the raw diff. Start broad enough for a reader who is new to the subsystem, then narrow to the specific concepts affected by the change.
14	- Intuition: Explain the core idea behind the change. Use concrete examples and toy data where helpful. Focus on the essence before the details.
15	- Code: Walk through the code at a high level. Group changes by concept or behavior, not by raw file order, unless file order is genuinely clearer.
16	- Behavior And Proof: Explain what should behave differently now. Link or cite tests, commands, screenshots, videos, traces, logs, or other proof artifacts when available. Clearly state anything not verified.
17	- Risks And Follow-Ups: Call out important edge cases, residual risk, migration concerns, product decisions, or follow-up work.
18
19	## Change-Mode Style
20
21	Write with clear narrative flow. Teach the change and its surrounding subsystem; do not dump a diff summary.
22
23	Use:
24
25	- callouts for key concepts, definitions, and important edge cases,
26	- simple HTML diagrams or figures when they make the system easier to understand,
27	- examples with realistic data or states,
28	- a responsive layout that is readable on desktop and phone.
29
30	Avoid:
31
32	- Notion output,
33	- quizzes,
34	- ASCII diagrams,
35	- pretending unverified behavior was tested,
36	- copying large raw diffs into the page without explanation.
37
38	## Change-Mode Diagrams
39
40	Prefer a small number of reusable diagram families throughout the page.
41
42	Useful diagram types:
43
44	- a simplified UI representation for UI changes,
45	- a system/data-flow diagram showing components and example data,
46	- a before/after state diagram,
47	- a sequence of user action -> system response -> persisted state.
48
49	Use normal HTML and CSS for diagrams. Do not use ASCII art.
50
51	## Closeout
52
53	Before reporting completion:
54
55	1. Complete the `/explain-report` closeout checks.
56	2. Confirm the report includes the change-mode sections or clearly justified equivalents.
57	3. Confirm changed behavior is separated from proof and from unverified expectations.
58	4. Return the absolute HTML path and mention any residual uncertainty.

People who liked this also viewed

6 picks

Type

explain-diff

34stars4forks

View on GitHub

How to install explain-diff?

minghinmatthewlam/agent-guards/explain-diff

$npx -y skills add minghinmatthewlam/agent-guards --skill explain-diff

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Explain Diff
2
3	Read and follow `../explain-report/SKILL.md`, then apply the code-change requirements below using Change mode.
4
5	Create a focused, readable HTML explanation of the specified code change. The report should help the user understand the surrounding subsystem and retain the important implementation knowledge, not merely inventory modified files.
6
7	This skill is for human understanding, not verification. Do not replace tests, screenshots, videos, logs, or other proof artifacts. If proof artifacts exist, link to them from the explanation.
8
9	## Change-Mode Sections
10
11	Include:
12
13	- Background: Explain the existing system needed to understand the change. Explore surrounding code, not just the raw diff. Start broad enough for a reader who is new to the subsystem, then narrow to the specific concepts affected by the change.
14	- Intuition: Explain the core idea behind the change. Use concrete examples and toy data where helpful. Focus on the essence before the details.
15	- Code: Walk through the code at a high level. Group changes by concept or behavior, not by raw file order, unless file order is genuinely clearer.
16	- Behavior And Proof: Explain what should behave differently now. Link or cite tests, commands, screenshots, videos, traces, logs, or other proof artifacts when available. Clearly state anything not verified.
17	- Risks And Follow-Ups: Call out important edge cases, residual risk, migration concerns, product decisions, or follow-up work.
18
19	## Change-Mode Style
20
21	Write with clear narrative flow. Teach the change and its surrounding subsystem; do not dump a diff summary.
22
23	Use:
24
25	- callouts for key concepts, definitions, and important edge cases,
26	- simple HTML diagrams or figures when they make the system easier to understand,
27	- examples with realistic data or states,
28	- a responsive layout that is readable on desktop and phone.
29
30	Avoid:
31
32	- Notion output,
33	- quizzes,
34	- ASCII diagrams,
35	- pretending unverified behavior was tested,
36	- copying large raw diffs into the page without explanation.
37
38	## Change-Mode Diagrams
39
40	Prefer a small number of reusable diagram families throughout the page.
41
42	Useful diagram types:
43
44	- a simplified UI representation for UI changes,
45	- a system/data-flow diagram showing components and example data,
46	- a before/after state diagram,
47	- a sequence of user action -> system response -> persisted state.
48
49	Use normal HTML and CSS for diagrams. Do not use ASCII art.
50
51	## Closeout
52
53	Before reporting completion:
54
55	1. Complete the `/explain-report` closeout checks.
56	2. Confirm the report includes the change-mode sections or clearly justified equivalents.
57	3. Confirm changed behavior is separated from proof and from unverified expectations.
58	4. Return the absolute HTML path and mention any residual uncertainty.

People who liked this also viewed

6 picks

Type