socratic-clarification

Guides structured clarification rounds and approval gates before implementation work begins.

Updated May 21, 2026
One-click install
npx skills add https://github.com/Sighthesia/just-demand --skill socratic-clarification-sighthesia
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: socratic-clarification
Source: https://github.com/Sighthesia/just-demand/tree/main/.opencode/skills/socratic-clarification
Command: npx skills add https://github.com/Sighthesia/just-demand --skill socratic-clarification-sighthesia

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Agents often jump straight into coding on vague requests, causing mismatched implementations, role drift, and wasted effort. This Skill enforces progressive clarification and explicit user approval before any code changes, so the final result matches what the user actually wanted. ## Core Features & Use Cases - Risk-proportional hard gate: Low-risk work (read-only investigation, verification) proceeds immediately, while high-risk work (code changes, architecture decisions) requires an approved decision surface first. - Structured questioning rounds: Three progressive rounds covering intent and expected outcome, current reality, and constraints, followed by a 2-3 approach comparison with a recommendation. - Specialized decision surfaces: Provides templates for UI/visual drift approvals, diagram intent cards, analysis and tuning tasks, and vague correction feedback via a two-stage option flow. - Use Case: A user says "the animation feels off." Instead of guessing, the agent presents dimension options (timing, spacing, motion), pins the target state through contrast choices, and gets approval on a visible-effect card before editing any code. ## Quick Start Ask the agent to clarify the expected outcome and propose approaches before implementing my requested change.

Frequently Asked Questions about socratic-clarification

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I stop an AI agent from coding before clarifying requirements?▼

Use a hard-gate clarification skill that blocks edits, subagent dispatch, and task promotion until the user approves a final artifact. High-risk work requires an expected effect, compared approaches, and explicit approval; low-risk read-only work proceeds directly.

How to handle vague bug feedback from users with an AI agent?▼

Apply a two-stage option flow: first offer dimension options (color, spacing, timing, logic) to locate the deviation, then present contrast choices to pin the target state. This minimizes what the user must type instead of forcing a prose description.

When should an AI agent ask questions versus proceed directly?▼

Classify work by risk level. Read-only investigation, standard verification, and evidence gathering proceed without permission. Code modification, scope expansion, or architecture changes require the full approval cycle with a decision surface.

What is a decision surface in agent clarification workflows?▼

A decision surface is a compact approval artifact showing the final expected effect, 2-3 compared approaches with a recommendation, scope, anti-outcomes, and visible acceptance criteria. It lets users approve or redirect work before implementation starts.

Why does long-context drift happen in AI analysis conversations?▼

After three or more turns on the same phenomenon, agents may adopt the user's assumed explanation too early. A reset structure summarizing established facts, uncertainties, and at-risk assumptions prevents premature narrowing and overconfidence.