diffwalk is better as a conversation than a lecture
diffwalk's marketed flow is one-shot: your coding agent captures the diff, writes the entire walkthrough, and hands you a rendered review to read. That works for sharing, but when the goal is understanding what the agent just changed, a finished lecture is the wrong shape — you read passively, and the agent's framing never gets challenged.
Two changes made it click for me.
Publish is not part of the loop. diffwalk publish only mints a share link. For your own comprehension, diffwalk view (loopback-only) is already the end of the pipeline — and often you don't need the browser at all:
diffwalk changes # list captured blocks
diffwalk change change-009 # read one block in the terminal
Interleave instead of pre-authoring. Instead of letting the agent write all of explanations.yaml up front, go one block at a time: the agent explains the block and gives its own take (correctness, risks, simpler alternatives), then stops and waits. I answer with mine. We decide jointly whether the block deserves a GitHub comment — the draft is shown in full and posted only after I confirm the exact text. Then, next block.
The agreed explanation for each block still lands in explanations.yaml as the loop runs, so a final diffwalk check doubles as "did we actually cover every change". The review conversation produces the walkthrough document as a side effect, instead of the document replacing the conversation.
One implementation note: I didn't edit diffwalk's own SKILL.md — it ships through npm and an update would clobber the edit. The pair-review loop lives in a separate custom skill beside it.