---
name: socratic
description: 'Internal gate of /gh:issue per V23 — sharpen vague intent → PilotSpec-ready draft before `gh issue create`. ⊥ user-invoked surface. Convergence criteria: explicit goal ∧ (≥ 1 acceptance criterion ∨ repro step) ∧ (cite §V/§T ∨ flag ⊥-spec). Single-question Socratic loop w/ just-in-time teaching overlay — when answer reveals gap ∨ implicit assumption, surface distinction in 1-2 sentences before next question. Concrete first-turn input passes gate ≤ 1 turn (zero-friction); vague triggers dialogue until criteria met. Triggered internally from /gh:issue Phase 1 only.'
allowed-tools: AskUserQuestion, Read, Grep
---

# Socratic — sharpen intent → filable issue

## Loop

1. ask 1 question
2. wait for answer
3. pick next question ∈ {clarify, scope, boundary, success, frame} ∨ converge
4. converge → draft issue → confirm → return to /gh:issue Phase 2 (github-issue-create)

∀ turn: 1 question. ¬ batched. ¬ checklist tone.

## Question pool

| category | fires when                      | shape                                                         |
| -------- | ------------------------------- | ------------------------------------------------------------- |
| clarify  | symptom is vague                | "what specifically — input → observed vs expected?"           |
| scope    | ask feels epic-shaped           | "what's the smallest change that removes the pain?"           |
| boundary | unclear what stays untouched    | "what's working today that must keep working?"                |
| success  | no acceptance criterion         | "how do we know it's fixed without re-asking you?"            |
| frame    | user names a fix, not a problem | "is that the problem, or your current guess at the solution?" |

pick by what's most missing. ¬ re-ask what user already supplied.

## Tone

interrogate the problem, ¬ the user. questions assume user is right ∧ probe the _statement_, not their judgment. ¬ "are you sure?" → "what would falsify this?"

## Code reads

read code reactively, ⊥ preemptively.

- ⊥ allowed: scan repo before any questions to "find the bug". undermines dialogue ∧ duplicates /gh:issue's broad investigation.
- ✓ allowed: user cites specific `file:line` ∨ symbol ∨ path → read that target. user claims behavior is broken w/o data → spot-check to verify claim before next question.

shape: "looking at `<file>:<line>`, [observable fact] — given that, [next question]". ¬ "I think the bug is X". model verifies, user diagnoses.

scope cap: ≤ 2 reads per turn. broader sweep needed → stop dialogue, return to /gh:issue Phase 2 for codebase investigation.

## Teach

education is an overlay, ¬ a separate phase. when an answer reveals a gap, surface the distinction in 1–2 sentences, then ask the next question. ¬ lecture, ¬ tangent.

teach when:

| trigger                                    | distinction to surface                                   |
| ------------------------------------------ | -------------------------------------------------------- |
| user names a fix as the problem            | symptom vs cause vs solution                             |
| user offers an unfalsifiable success crit  | what makes a criterion verifiable (observable + bounded) |
| user conflates scope w/ ambition           | smallest-change seam vs total redesign                   |
| user assumes a behavior is broken w/o data | observed vs expected vs assumed                          |

shape: "[concept in 1 line] — given that, [next question]". user learns by using the distinction on their own problem, ¬ by being told.

## Convergence

ready: ∃ all:

- observable symptom (bugs) ∨ concrete behavior delta (features)
- smallest-version scope
- verifiable success criterion

output shape feeds PilotSpec cleanly:

- bug → §B candidate (symptom + smallest-fix + invariant-to-prevent-recurrence)
- feature/refactor → §T candidate (task + §V verification line)

precision here ⇒ /sdd:spec has less work later.

≥3 turns w/o convergence → offer escape: "I have enough for a rough issue — file now ∧ refine in comments, or keep going?"

## Escape hatch

"just file it" ∨ "skip the questions" ∨ "I know what I want" → stop dialogue. ⊥ bypass V23 gate — evaluate current state against convergence criteria; gaps unmet → either ask once for missing piece ∨ proceed to /gh:issue Phase 2 w/ explicit `## Unresolved` callouts in body documenting each unmet criterion. preserves V23 validity bar (gaps visible to team) while honoring user's "done thinking" signal.

## Handoff

draft title + body summary → show user → on confirm, return control to /gh:issue Phase 2 (github-issue-create skill) w/ drafted text. ¬ file without explicit confirmation. body formatting (steno style, conventional commits, label selection, codebase investigation) is Phase 2's job — ¬ duplicate here.

## Boundary

¬ root-cause debugging — that's /sdd:backprop's job once the bug is filed. socratic stops at "what's the observable problem", not "why is it happening".