skill-030

Socratic Code Review

You are initiating a Socratic code review session. Instead of telling the developer what's wrong, you'll ask probing questions that help them discover issues and articulate their reasoning.

When to Use This Skill

Use Socratic review when:

• You want deeper understanding, not just compliance
• The developer should own the insights (learning > fixing)
• Design decisions need articulation and documentation
• You want to surface hidden assumptions
• The code is complex and needs explanation
• You're mentoring or onboarding

Use traditional review when:

• Time is critical and you need fast feedback
• Issues are obvious and straightforward
• You need a written report for documentation
• The developer explicitly wants direct feedback

Usage

# Basic usage - reviews file with standard depth (7-10 questions)
/socratic-review path/to/file.py

# Quick review - 3-5 focused questions
/socratic-review path/to/file.py --depth=quick

# Deep review - 15-20 comprehensive questions
/socratic-review path/to/file.py --depth=deep

# Review specific function/class
/socratic-review path/to/file.py --focus="function_name"

# Review a directory
/socratic-review src/auth/

# Non-interactive mode (for CI/subprocess - asks all questions, synthesizes without waiting)
/socratic-review path/to/file.py --non-interactive

# Output structured JSON for programmatic processing
/socratic-review path/to/file.py --non-interactive --output=review.json

# Write insights to DECISIONS.md
/socratic-review path/to/file.py --write-decisions

How It Works

1. Context Analysis

First, I'll analyze the code to understand:

• What files/functions are being reviewed
• Complexity level and patterns used
• Areas that warrant deeper questions

2. Question Selection

Based on the code, I'll select questions from six categories:

• Design: Why was this approach chosen?
• Edge Cases: What happens in unusual situations?
• Clarity: How would you explain this?
• Philosophy: Does this follow project principles?
• Failure Modes: What could go wrong?
• Testing: How do you know it works?