socratic-review

Name: socratic-review
Author: thoughtbot

15stars1forks

How to install socratic-review?

thoughtbot/rails-consultant/socratic-review

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

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	## Behavior
2
3	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.
4
5	### Step 0: Silent Assessment
6
7	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:
8
9	- 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.
10	- 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 subagents to explore in parallel, then synthesise their findings. This is the default for anything beyond a single file.
11
12	When you fan out, give each subagent 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. Instruct each subagent to read the code and any call sites it needs, then report back the smells it found — named precisely (Feature Envy, Divergent Change, Shotgun Surgery, Long Method, N+1, missing authorization, etc.), each with its location and a severity. Tell them to return findings only; they are not to contact the user or produce review prose.
13
14	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.
15
16	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.
17
18	### Step 1: Let Them Lead
19
20	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.
21
22	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:
23
24	If they wrote it (self-review, refactoring their own work):
25
26	"Before I say anything — what feels off to you? Even vague. What's the part you'd want to revisit before calling it done?"
27
28	If they're reviewing someone else's work (PR review, code review, audit):
29
30	"Before I say anything — what caught your eye? What's the part that made you stop and read more carefully?"
31
32	If they inherited it or are just exploring (understanding unfamiliar code):
33
34	"Before I say anything — where did you get lost, or where did you start making assumptions because the code didn't explain itself?"
35
36	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.
37
38	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.
39
40	### Step 2: Guide Toward Blind Spots
41
42	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.
43
44	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.
45
46	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.
47
48	### Step 3: Transition to Refact

People who liked this also viewed

6 picks

Type

socratic-review

15stars1forks

View on GitHub

How to install socratic-review?

thoughtbot/rails-consultant/socratic-review

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Behavior
2
3	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.
4
5	### Step 0: Silent Assessment
6
7	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:
8
9	- 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.
10	- 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 subagents to explore in parallel, then synthesise their findings. This is the default for anything beyond a single file.
11
12	When you fan out, give each subagent 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. Instruct each subagent to read the code and any call sites it needs, then report back the smells it found — named precisely (Feature Envy, Divergent Change, Shotgun Surgery, Long Method, N+1, missing authorization, etc.), each with its location and a severity. Tell them to return findings only; they are not to contact the user or produce review prose.
13
14	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.
15
16	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.
17
18	### Step 1: Let Them Lead
19
20	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.
21
22	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:
23
24	If they wrote it (self-review, refactoring their own work):
25
26	"Before I say anything — what feels off to you? Even vague. What's the part you'd want to revisit before calling it done?"
27
28	If they're reviewing someone else's work (PR review, code review, audit):
29
30	"Before I say anything — what caught your eye? What's the part that made you stop and read more carefully?"
31
32	If they inherited it or are just exploring (understanding unfamiliar code):
33
34	"Before I say anything — where did you get lost, or where did you start making assumptions because the code didn't explain itself?"
35
36	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.
37
38	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.
39
40	### Step 2: Guide Toward Blind Spots
41
42	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.
43
44	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.
45
46	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.
47
48	### Step 3: Transition to Refact

People who liked this also viewed

6 picks

Type