debriefing-code-changes

Output Contract

Produces: a Code Change Debrief Markdown report grounded in a git diff or commit range, with: change summary, files-to-understand shortlist, per-change explanation, pattern/concept map, caveats, practical quiz, and optional durable notes.

Does NOT produce: generic CS lessons, ungrounded pattern spotting, code edits, refactors, or deploy approval.

Hands off to: the developer's learning loop — they read the debrief, answer the quiz, then decide whether to save notes, add tests, or request a separate code review/fix skill.

---

Process

Phase 1 — Collect the actual change set

1. Ask for or infer the target range: unstaged diff, staged diff, last commit, branch diff, or explicit commit range.
2. Prefer git facts over chat memory. Run scripts/collect_diff.py or equivalent git commands to capture: changed files, diff stats, commits, file excerpts, and touched functions/classes where available.
3. If the diff is too large, shortlist the 3–7 files with the highest learning value: core logic, new abstractions, boundary code, data model changes, tests, and security-sensitive paths.
4. If no diff or commit range exists, stop and ask for one. Do not debrief from the chat transcript alone.

Why: the lesson lives in code the developer now owns. Chat transcripts are noisy and often explain intentions that never landed in the repository.

Read references/debrief-rubric.md before writing the report.

---

Phase 2 — Explain intent and structure per non-trivial change

For each selected change, produce this block:

### [File or subsystem]
What changed: [plain-English summary]
Why it was shaped this way: [architecture/design rationale inferred from the code]
Key code to read: [file:function or file:line when available]
Pattern or concept: [only if visibly present in the code]
Tradeoff accepted: [what this design makes easier vs harder]
One thing to watch: [edge case, coupling risk, missing test, performance/security caveat]