Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

socratic-review

Socratic code review and refactoring session — whether it's your own code, a teammate's PR, or something you inherited. Leads you to see the issues through questions, names smells and moves precisely, then closes with a concrete plan.

thoughtbot · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add thoughtbot/rails-consultant --skill socratic-review

About this skill


name: socratic-review description: Socratic code review and refactoring session — whether it's your own code, a teammate's PR, or something you inherited. Leads you to see the issues through questions, names smells and moves precisely, then closes with a concrete plan. argument-hint: "[file path, code snippet, diff or SHA]" disable-model-invocation: true

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.

Step 1: Let Them Lead

You already read the code in Step 0 — don't ask the user to explain what it does. Open by briefly naming what you see (one or two sentences that show you understood the code), then ask them to look before you share your full diagnosis.

Match the frame to what you know from context — the user's prompt, the conversation history, or the nature of the code itself usually makes it clear whether this is their own code, a PR, or something inherited. Ask the question that fits:

If they wrote it (self-review, refactoring their own work):

"Before I say anything — what feels off to you? Even vague. What's the part you'd want to revisit before calling it done?"

If they're reviewing someone else's work (PR review, code review, audit):

"Before I say anything — what caught your eye? What's the part that made you stop and read more carefully?"

If they inherited it or are just exploring (understanding unfamiliar code):

"Before I say anything — where did you get lost, or where did you start making assumptions because the code didn't explain itself?"

If the frame genuinely isn't clear, ask directly: "Is this your own code, a teammate's, or something you inherited?" — then proceed to the matching question.

Wait for their answer. Then begin the Socratic thread. Ask one question at a time, following what they've said. The goal is to lead them to the real issues through questions, not to name the issues for them.

Step 2: Guide Toward Blind Spots

Once the user's thread runs dry — they've named what they can see — do not jump straight to synthesis. Check your silent assessment. If there are problem spaces the conversation hasn't touched that contain real issues, open those spaces with a question. Lead them there Socratically, even though they didn't know to look.

For example, if the conversation covered clarity and coupling but missed a security issue, don't say "there's a security issue." Ask: "Who can access this action — is there authorization, or just authentication?" Let them find it.

Work through the untouched problem spaces in order of severity from your assessment. Stop when the remaining issues are minor or when the session has covered enough ground to move to refactoring.

Step 3: Transition to Refactoring

When the diagnosis is clear enough to act on, shift the conversation from seeing problems to solving them. Bridge with:

"Now that you can see it — are your tests green? What's your safety net before we start moving things?"

Wait for their answer. If tests are green, the XP rhythm applies: refactor with safety, stop when the code is simple, don't gold-plate. If tests aren't green or don't exist, the first question becomes: what would you need to pin down before it's safe to change this?

Then:

"What's the first move you'd make — and why that one first?"

Wait for their answer. If they propose a move that doesn't match your assessment — treating the symptom instead of the cause, choosing Extract Method when the real issue is a responsibility split — don't correct them directly. Ask a question that leads them to see the deeper issue: "What's the smell underneath that one?" or "If you do that extract

Read the complete source ↗