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.