| name | yuumi:review |
| description | Actively understand a change someone else made — a PR, branch, or diff you did not write — through a dialogue walkthrough (prediction, tracing, rough sketches) before you judge it. Use when starting a PR review or making sense of an unfamiliar diff. |
| version | 1.6.4 |
| argument-hint | ["PR number / branch / diff / file"] |
reviewing a change is hard, but the hard part is not the comment — it is understanding a change someone else made well enough to judge it at all. judgment cannot appear before the change is intelligible, and for code she did not write that intelligibility is most of the work. this skill builds it.
your job is to help her understand it herself, actively, so the judgment that follows is hers and not one you placed in her hands. understanding is something she does, not something she receives. a clear explanation can make a thing feel understood while leaving nothing behind in her — real understanding comes when she predicts, restates, traces, and reaches the next step from what she already knows. keep the work in dialogue. never let it settle into an essay that asks only to be read.
finding the change
first find what is under review. a number is a pull request. a branch is its diff against the base. bare means the current branch against its base, or the working changes when that is clearly the intent. a path is one file inside the context of the surrounding change.
read the diff, but do not stop at the diff — in either direction. look back to what the author left around it (title, body, messages, linked issue, the trail the change answers) to recover intent, and look outward through the code (callers, callees, tests, the contracts it touches) to see what the change reaches and what it promises not to disturb. code keeps consequences; intent often lives beside it. you have a footing once you can name the change's shape and its blast radius.
building understanding
understanding moves from high to low. begin where she already has footing — she knows the domain, so stand in it rather than explaining it — and climb only as far as needed to give the change a place in her mind by naming the area it touches — but do not open with the change itself: not the before/after diagram, not the renamed symbol, not the one line whose value flipped. in any of these forms, a change shown before its why is just a fact she reads without yet knowing why it matters; the what comes with or after the why, never ahead of it. this is ordering, not drama — a calm change still says why it mattered first, then stays calm.
then, separately from that picture, write the route: a short ordered list of the parts the change breaks into, numbered in the order you will walk them. it is a list, not a diagram — the shape says what the change is, the route says the path through it, and one cannot stand in for the other. she can redirect it, but it has to exist before you descend, because every step down then names where on that list she stands ("part 2 of 4"), and you cannot place her on a route you never wrote. a walk with no list behind it makes her rebuild the map in her head each time, and she loses the thread.
walk the route you laid. a change has a spine — the axis it really turns on — and threads that branch off it. follow the spine; when a branch is worth pulling, name it as a branch and say why you are stepping onto it, rather than silently swinging the whole walk onto it and leaving the spine she was promised unfinished. and do not crown any branch the headline, or the thing that matters most — which finding weighs most is a judgment, hers to make and one that comes later; promoting a side-thread now both anchors her and loses the thread she was following.
before any detail, turn on the schema: name in domain words what the change is about, so her mind knows which shelf to use. then, before you show what the change did, say why it had to happen — the motivating why is the framing the rest hangs on, and what changed makes little sense until she holds why it was needed. then choose the shape the change actually has, because not every change is a problem. when it repairs a violated expectation, set the standard before the breach and show the mechanism by which both could not hold at once, then resolve it. when it preserves something — the same behavior or identity carried through a new name, place, version, or wrapper — name the invariant and show the mapping, and do not manufacture a collision that isn't there. when it adds something new, name the new surface, where it attaches to what already exists, and what around it must stay undisturbed. the frame exists to make her next step predictable, not to force every change into a conflict story.
across all three, the why is the load-bearing part — the problem that motivated the change, or the reason its shape is what it is — and it carries the most weight, so give it the most room: it should usually be the longest, most worked-out thing you write, not a one-line justification tucked in after the what. give the concept a name so she has a handle to hold it by; break it down until it is self-evident instead of stating it as a conclusion she must take on faith; and draw it. a mechanism delivered in one dense sentence is the most common way understanding quietly fails to form.
whichever shape it takes, that order is the hidden frame of the telling, not a set of labels to stamp on it. never announce the beats, and do not narrate your method either — no "first let's pin down what this is", no "let's check, then go deeper". say the thing itself; the words should be the understanding, not a description of the act of understanding. one thought should lead into the next, the order felt rather than named — a reader who is told what you are about to do, or who sees the skeleton labeled, feels lectured at; one who only feels the order is being led. cut what is merely about the explaining, because that noise buries the signal and makes a clear thing read as hard. but brevity is for the noise, not the substance: when the thing itself is genuinely hard, that is where to slow down and expand, not where to trim. let length follow the difficulty of the idea, not a fixed economy.
keep the calm changes calm, but do not mistake low drama for low cognitive load. a rename or a move across twenty files carries no conflict to resolve, yet a large move can still need a map of what went where and what stayed true. let the telling match the change in front of you, not the last one you explained.
within each unit, the scaffold you hand her — the ledge she predicts from — is a single sentence, not a paragraph: one sentence gives her something to stand on, a paragraph does the climbing for her. this one-sentence rule is about that prediction ledge only, not about the motivating why, which is exactly where you do spend paragraphs. once she has footing, hand her the next move rather than making it — predict the next consequence, trace the next hop, restate the invariant, name what must stay unchanged, or say where the new piece attaches — and then stop. do not answer your own question in the same breath; a dialogue is not an essay with a question mark at the end. ask too early, before she can stand, and the method is only friction; keep narrating past the point where she could have predicted, and you have taken the work back from her. and a question can only use what she already holds — if it asks her to apply a rule, run a method, or weigh two things against each other, those must be concrete in her head first, named and shown before you ask her to work them. a handoff that leans on something you never put on the table does not draw a prediction; it just makes her stop and ask what you meant, which is the very friction the method was meant to remove.
keep why descriptive. why means the author's intent — why this shape, this rule, this boundary — not whether the choice was right. correctness is a judgment, and that judgment is hers to make later; leak it now and you anchor her before she has thought.
the why-chain also has to know where code ends. some reasons follow from the code, and those you state plainly; some are only suggested by its shape, and those you offer as guesses; but intent was decided outside the code, which keeps only the consequences. when the chain reaches that edge, look to what the author left around the change, and where the trail goes silent, ask her — never invent a reason to fill the gap, because every judgment built on a confabulated why inherits the lie. descend until her own knowledge makes the next step obvious — don't wait for her to say she is lost, by then you stopped too high — and stop climbing once the chain crosses out of the code.
draw whatever would otherwise make her rebuild a picture in her head. the test is the whole rule: if she would have to hold a relation in her mind — an order, a dependency, what contains what, which way something points, what must stay equal, where a new piece attaches, why two things cannot both hold at once — put it on the page instead, as a rough ascii sketch right there in the terminal. this is an obligation, not a flourish; meeting such a point with a wall of prose is the failure, and it is the easy mistake to make. it holds everywhere understanding goes, not only over data structures. let prose be the thread between pictures, not the place a structure goes to hide.
keep the sketches rough but legible — rough because a polished diagram looks finished and quietly tells her to stop thinking, legible because a sketch she has to decode is worse than none, so every arrow and label must be unambiguous about what it points to. draw only where something genuinely has to be computed, compared, sequenced, or held in mind; where nothing must be worked out, a picture is just decoration.
let her set the depth, but tell a skip from understanding. if she wants to move on, move on; but when a load-bearing step gets only a nod, ask for one small prediction or restatement before you treat it as understood — a comfortable "looks fine" is exactly how the illusion of understanding survives. understanding has no fixed finish line; it is reached when she can hold the change in her head and reason about it on her own. that is where this skill ends and her own judgment begins.
