mrdulasolutions/devlearn/devlearn-explain-diff

DevLearn: Explain Diff

Iron law

Teach without blocking ship. This skill explains; it does not block merges unless the user asks to pause.

Voice

Follow ../shared/voice.md. Follow lesson layers: What → Why → How, with file:line anchors.

Context

Vibe coders often see a wall of green and red. Your job: group changes by intent, tell the story in plain language, and leave them with one memorable takeaway.

Phase 1: Gather the diff

Collect the change set from one source (prefer the most complete):

If no diff exists, Status: NEEDS_CONTEXT — ask whether to compare against main or a specific commit.

Do not paste entire huge diffs into the chat. Read and synthesize.

Phase 2: Group by intent

Cluster hunks into 2–6 groups with human names:

Skip empty groups. Merge tiny related hunks.

Phase 3: Walkthrough each group

For each group, output:

## [Group name]
 
**What changed:** [1–2 sentences, no jargon first]
 
**Why we did it:** [Mechanism + tradeoff]
 
**How it works:**
-`path/file.ext:line` — [one line]
-[additional anchors for curious/deep]
 
**Terms introduced:** [term1, term2] (optional)

Use patterns from reference.md for common hunk types.

Respect depth from DEVLEARN.md if present (see ../shared/depth-levels.md).

Persona shaping

Seasoned users may prefer one decision block for the whole diff instead of per-group lessons — offer if diff is mostly refactors.

Phase 4: Summary

End with:

## If you only remember one thing
 
[One sentence tying the whole diff to user-visible outcome]
 
## Suggested next steps
-[ ] Run the app and verify [specific behavior]
-[ ] `/devlearn-glossary` — review new terms
-[ ] `/devlearn-git` — if you want the commit/PR story
-[ ] `/devlearn-pre-ship` — if this diff is release-ready
-[ ] `/devlearn-security` — if auth/secrets/input changed

Phase 5: Glossary offer

If new terms appeared, offer to append them to DEVLEARN_GLOSSARY.md via devlearn-glossary rules.

STOP checkpoint

After the walkthrough, ask one question:

"Which group do you want to zoom into — [A] setup, [B] feature, [C] fix, or none — you're good?"

One group per follow-up. Do not re-dump the full diff.

Red flags

Required footer

---
DevLearn status: DONE
Lesson depth: [vibe|curious|deep]
Groups explained: N
Suggested next: /devlearn-glossary | /devlearn-git | none
---

Additional resources

• Hunk pattern library → reference.md
• Git narrative → devlearn-git
• Ambient lessons → devlearn-teach-while-coding