{
  "markdown": "# Socratic\n\nSocratic turns vague requests into immediately usable prompts by detecting the missing information that matters most, asking the minimum necessary questions, and stopping as soon as the prompt is ready to run.\n\n## Behavior\n\nSocratic is intentionally not always-on. It is a manual clarification tool.\n\nCore capability:\n\n- Detect the highest-leverage missing information\n- Ask the minimum necessary questions\n- Produce a prompt that is short, specific, and immediately usable\n- Prioritize different unknowns for common prompt families such as coding, design, writing, planning, and automation\n\nOperating modes:\n\n- `default`: ask 0 to 3 questions, one per turn, and stop as soon as the prompt is usable\n- `lite`: ask exactly 0 or 1 question; skip questioning if already clear, otherwise ask only the single highest-leverage question\n- `strict`: reserved for a future mode focused on tighter output format and constraint handling, not extra questioning\n\nCore rules:\n\n- Ask at most 3 questions\n- Ask one question per turn\n- Stop early if the request is already clear\n- Avoid generic “tell me more” questions\n- Prefer questions about success criteria, constraints, output shape, rejection criteria, or usage context\n- Return a final prompt that is short, specific, and immediately usable\n\nDomain-aware questioning:\n\n- Socratic remains general-purpose, but it silently infers common prompt families and adjusts question priorities.\n- In v1, the core domains are `coding`, `design`, `writing`, `planning`, and `automation`.\n- If domain confidence is low or mixed, Socratic falls back to the general-purpose question framework instead of forcing a weak guess.\n\n## Usage Examples\n\n### 1. Vague Feature Request\n**User:** `/soc Add auth to my Express app.`\n**Socratic:** \"Which authentication strategy do you prefer (e.g., Passport.js with JWT, NextAuth, or a custom session-based approach)?\"\n**User:** \"Passport with JWT.\"\n**Socratic:**\n> **Final Prompt:**\n> Implement authentication in the Express application using Passport.js and JSON Web Tokens (JWT). Include routes for user registration, login, and a protected profile route. Use a local strategy for initial authentication and ensure passwords are hashed before being stored in the database.\n>\n> Why this works: Specifying the exact library (Passport.js) and strategy (JWT) removes the primary ambiguity from the initial request.\n\n### 2. Request for a Tighter Prompt\n**User:** `/soc Make this prompt better: 'Write a script to scrape a website.'`\n**Socratic:** \"What is the target website or type of data you need to extract (e.g., product prices from an e-commerce site, news headlines), and which language/library should the script use?\"\n**User:** \"Python with BeautifulSoup to get stock prices from a table.\"\n**Socratic:**\n> **Final Prompt:**\n> Write a Python script using the BeautifulSoup library to scrape stock price data from a HTML table on a specified financial news website. The script should handle basic error checking for network requests and output the scraped data into a structured CSV format.\n>\n> Why this works: Adding the specific library, target data, and output format transforms a generic request into an actionable technical task.\n\n### 3. Explicit Socratic Invocation (Already Clear)\n**User:** `/soc Write a React component for a primary button that accepts 'label' and 'onClick' props, styled with vanilla CSS.`\n**Socratic:**\n> Prompt already clear. Tightened:\n> Create a functional React component named `PrimaryButton` that accepts `label` (string) and `onClick` (function) as props. Include a companion vanilla CSS file for styling, ensuring the button has a consistent padding, font size, and a hover state transition.\n\n## Compatibility Matrix\n\n| Tool | Packaging | Install Surface | Invocation Model |\n| :--- | :--- | :--- | :--- |\n| Claude Code | Project or user slash commands | `.claude/commands/` | Manual slash commands |\n| Codex | Local plugin + skill | `plugins/socratic/` and `.agents/plugins/marketplace.json` | Manual plugin/skill use |\n| Gemini CLI | Repo-root extension | `gemini-extension.json`, `GEMINI.md`, `commands/` | Manual extension commands |\n\n## Install\n\n### Claude Code\n\nProject-local install:\n\n```bash\nmkdir -p .claude/commands\ncp .claude/commands/soc.md .claude/commands/soc-lite.md .claude/commands/socratic.md /path/to/your-project/.claude/commands/\n```\n\nUser-level install:\n\n```bash\nmkdir -p ~/.claude/commands\ncp .claude/commands/soc.md .claude/commands/soc-lite.md .claude/commands/socratic.md ~/.claude/commands/\n```\n\nCommands:\n\n| Command | Purpose |\n| :--- | :--- |\n| `/soc` | Default mode with 0 to 3 clarifying questions |\n| `/socratic` | Alias for `/soc` |\n| `/soc-lite` | Lite mode with exactly 0 or 1 clarifying question |\n\n### Codex\n\nRepo-local plugin install:\n\n1. Open Codex in this repo.\n2. Open `/plugins`.\n3. Search for `Socratic`.\n4. Install the local plugin.\n\nDirect skill install:\n\n```bash\nmkdir -p \"${CODEX_HOME:-$HOME/.codex}/skills/socratic\"\ncp .codex/skills/socratic/SKILL.md \"${CODEX_HOME:-$HOME/.codex}/skills/socratic/\"\n```\n\nNotes:\n\n- Socratic is manual-invocation by design.\n- This repo does not auto-enable a `SessionStart` hook for Socratic.\n\n### Gemini CLI\n\nInstall from the repo root:\n\n```bash\ngemini extensions install <repo-url-or-local-path>\n```\n\nFor local development:\n\n```bash\ngemini extensions link .\n```\n\nCommands after restart:\n\n| Command | Purpose |\n| :--- | :--- |\n| `/soc` | Default mode with 0 to 3 clarifying questions |\n| `/socratic` | Alias for `/soc` |\n| `/soc:lite` | Lite mode with exactly 0 or 1 clarifying question |\n| `/socratic:lite` | Alias for `/soc:lite` |\n\n## Shared Core\n\nThe canonical behavior lives in:\n\n- `skills/socratic-core/SKILL.md`\n\nAgent-specific wrappers should stay thin and point back to that core behavior whenever the host tool supports file references.\n\n## Evaluation Set\n\nThe current evaluation set contains 14 handcrafted prompt cases across coding, design, writing, planning, analysis, research, automation, frontend, and marketing.\n\nThese numbers describe the intended interaction profile of the current eval set. They are design targets, not measured production performance.\n\n| Metric | Result |\n| :--- | :--- |\n| Total benchmark cases | 14 |\n| Cases expected to finish in 0 questions | 5 |\n| Cases expected to finish in 1 question | 6 |\n| Cases expected to finish in 2 questions | 3 |\n| Cases expected to finish in 3 questions | 0 |\n| Median ideal question count | 1 |\n| Mean ideal question count | 0.86 |\n\nTarget question-count distribution:\n\n| Ideal questions | Cases | Share |\n| :---: | :---: | :---: |\n| 0 | 5 | 36% |\n| 1 | 6 | 43% |\n| 2 | 3 | 21% |\n| 3 | 0 | 0% |\n\nThis is the intended product shape: most vague prompts should be improved in 1 question, some need 2, and already-clear prompts should skip questioning entirely.\n\n## License\n\nMIT\n",
  "bytes": 6842,
  "sha": "0d05ce2d0458b883440a2fb717b224e637e4dd26164bfe0ca7e54bf43b777663",
  "repo_slug": "ycedrick/socratic",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ycedrick_socratic_1c15d29d/readme"
}