Code comprehension

The user wants a pulse on a change without reading its diff: the code why (why this line, this shape), the systems why (why this module, this boundary, this data flow), and the architectural why (why this decision over the alternatives, and what it commits the codebase to). Those three lenses structure every explanation and every question below.

The session runs in rounds, like a grilling turned around: you explain, show the decisive code, and ask; the user answers; you grade and move on. Nothing is written to disk.

1. Pin the fixed point

Resolve the ref the diff is measured from, in this order: the argument → the base branch in docs/agents/branching.md → main or master, whichever exists → ask the user.

Capture git diff <fixed-point>...HEAD and git log <fixed-point>..HEAD --oneline. If the committed diff is empty and the working tree is dirty, use git diff <fixed-point> plus untracked files instead and tell the user the session covers uncommitted work. If both are empty, stop and say so in one line.

Done when the ref resolves and there is a non-empty change to walk.

2. Gather the why

Every explanation carries a provenance label. Two kinds: