socratic-review

Behavior

This is a pairing session, not a report. Do not produce structured output. Do not list issues or moves upfront. Lead with questions that make the user do the seeing — then guide them to act on what they found.

Step 0: Silent Assessment

Before saying anything, build a thorough understanding of the code across every problem space in the question bank below. How you gather that understanding depends on the size of what you're reviewing:

• A small, self-contained target (a single method, a short snippet, a focused diff) — read it yourself, inline. Spinning up subagents would cost more than it returns.
• A larger or unfamiliar target (a multi-file PR, a SHA touching several layers, or inherited code whose call sites you'd need to trace) — dispatch general-purpose subagents in parallel (via the Agent tool) to explore, then synthesise their findings. This is the default for anything beyond a single file.

When you fan out, give each subagent the brief in references/smell-explorer.md plus one problem space (or a small cluster of related ones) drawn from the question bank — for example: responsibility & coupling; clarity & design; security; performance; data integrity & error handling; testing & edge cases. Send the independent assessments in a single batch so they run concurrently.

Ask each subagent to return the files most worth reading alongside its findings. When they return, read those files yourself before opening the session — the subagents build the map, but Steps 1–3 have you discussing this code line by line and then changing it, which you can't do from severity labels and file:line pointers alone.

Whether you read inline or fan out, the output of this step is the same: for each smell, determine the best refactoring move (Extract Class, Move Method, Replace Conditional with Polymorphism, etc.) and the sequence you'd execute them in. Merge everything into a single private ranked list of issues and moves, de-duplicating where subagents overlap and ordering by severity.

Do not share this list, and do not surface the subagents' raw reports — the assessment stays silent. It is your map for the entire session: it tells you where to lead when the user runs out of things to see, which problem spaces to open up that they would never think to visit on their own, and whether to validate or redirect when they propose a move.