Socratic Review

What it does

The Socratic Review skill facilitates a unique code review process where, instead of directly pointing out errors, the AI agent asks probing questions to guide the developer in identifying issues and articulating their reasoning. This approach aims for deeper understanding and ownership of insights by the developer, rather than simply achieving compliance with coding standards. The tool analyzes code and poses targeted questions across design, edge cases, clarity, philosophy, failure modes, and testing.

When to use it

• When you desire a deep understanding of the code beyond just fixing errors.
• To encourage developers to own their insights and learning.
• When design decisions require clear articulation and documentation.
• To uncover hidden assumptions within the codebase.
• During mentoring or onboarding processes for new team members.

Key capabilities

• Socratic Questioning: Poses targeted questions to guide code review, rather than providing direct feedback.
• Context Analysis: Analyzes code complexity and patterns to identify areas needing deeper investigation.
• Categorized Questions: Asks questions categorized as Design, Edge Cases, Clarity, Philosophy, Failure Modes, and Testing.
• Depth Levels: Offers three review depths: Quick (3-5 questions), Standard (7-10 questions), and Deep (15-20 questions).
• Focus on Specific Code Elements: Allows focusing the review on specific functions or classes.
• Non-Interactive Mode: Provides a non-interactive mode for automated code review processes, synthesizing results without user interaction.
• Output Options: Supports structured JSON output and writing insights to a DECISIONS.md file.

Example prompts

• /socratic-review src/auth/ (Reviews the entire src/auth/ directory)
• /socratic-review path/to/file.py --depth = quick (Performs a quick review of path/to/file.py)
• /socratic-review path/to/file.py --focus = "calculate_total" (Reviews only the calculate_total function in path/to/file.py)

Tips & gotchas

• This skill is designed for learning and understanding, not for rapid feedback or generating formal documentation.
• The review depth significantly impacts the time required; a "deep" review can take considerable time.
• For automated CI pipelines, use the --non-interactive flag to avoid requiring manual interaction.