Menü
Socratic interview to crystallize vague requirements
Guided onboarding wizard for Ouroboros setup
Execute a Seed specification through the workflow engine
Open or drive the Ouroboros settings GUI (browser, TUI, or conversational fallback)
Generate validated Seed specifications from interview results
Full reference guide for Ouroboros commands and agents
First-touch experience for new Ouroboros users
| name | interview |
| description | Socratic interview to crystallize vague requirements |
| mcp_tool | ouroboros_interview |
| mcp_args | {"initial_context":"$1","cwd":"$CWD"} |
Socratic interview to crystallize vague requirements into clear specifications.
ask_user — ask human-judgment questions through the active runtime's user-question surface.inspect_code — answer repo-local factual questions from exact local files before asking the user.call_mcp — use Ouroboros MCP tools for persistent interview state and seed generation.run_lateral_review — invoke lateral thinking subagents before milestone turns and direct-answer synthesis.web_research — fetch current external facts only when the interview genuinely depends on them.run_shell — run bounded local commands for version checks and repository inspection.refine_answer — confirm structured interpretations of free-text answers before forwarding them.maintain_ledger — keep ambiguity, gates, and unresolved decisions visible in the main session.run_closure_gate — audit readiness locally even when MCP reports seed-ready.restate_goal — restate the goal and require explicit approval before seed generation.seed-ready as permission to audit closure, not as completion.ooo interview [topic]
/ouroboros:interview [topic]
Trigger keywords: "interview me", "clarify requirements"
When the user invokes this skill:
Before starting the interview, check if a newer version is available:
# Fetch latest release tag from GitHub (timeout 3s to avoid blocking)
curl -s --max-time 3 https://api.github.com/repos/Q00/ouroboros/releases/latest | grep -o '"tag_name": "[^"]*"' | head -1
Compare the result with the current version in the active runtime's local plugin metadata (for Claude installs this is .claude-plugin/plugin.json).
ask_user capability:
{
"questions": [{
"question": "Ouroboros <latest> is available (current: <local>). Update before starting?",
"header": "Update",
"options": [
{"label": "Update now", "description": "Update plugin to latest version (restart required to apply)"},
{"label": "Skip, start interview", "description": "Continue with current version"}
],
"multiSelect": false
}]
}
claude plugin marketplace update ouroboros via the active runtime's run_shell capability (refresh marketplace index). If this fails, tell the user "⚠️ Marketplace refresh failed, continuing…" and proceed.claude plugin update ouroboros@ouroboros via the active runtime's run_shell capability (update plugin/skills). If this fails, inform the user and stop — do NOT proceed to the package-manager step.ouroboros-ai; do not require Claude-only commands or tools.ouroboros-ai by running these in order:
uv tool list 2>/dev/null | grep "^ouroboros-ai " → if found, use uv tool upgrade ouroboros-aipipx list 2>/dev/null | grep "^ ouroboros-ai " → if found, use pipx upgrade ouroboros-aipip install --upgrade ouroboros-ai" (do NOT run pip automatically)ooo interview again."Then choose the execution path:
The Ouroboros MCP tools are often registered as deferred tools that must be explicitly loaded before use. You MUST perform this step before deciding between Path A and Path B.
Use the active runtime's tool-discovery capability to find and load the interview MCP tool:
tool discovery query: "+ouroboros interview"
This searches for tools with "ouroboros" in the name related to "interview".
The tool will typically be named mcp__plugin_ouroboros_ouroboros__ouroboros_interview (with a plugin prefix). After runtime tool discovery returns, the tool becomes callable.
If runtime tool discovery finds the tool → proceed to Path A. If runtime tool discovery returns no matching tools → proceed to Path B.
IMPORTANT: Do NOT skip this step. Do NOT assume MCP tools are unavailable just because they don't appear in your immediate tool list. They are almost always available as deferred tools that need to be loaded first.
If the ouroboros_interview MCP tool is available (loaded via runtime tool discovery above), use it for persistent, structured interviews.
Architecture: MCP is a pure question generator. You (the main session) are the answerer and router.
MCP (question generator) ←→ You (answerer + router) ←→ User (human judgment only)
Role split:
inspect_code capability, or routes to the user when human judgment is needed.Start a new interview:
Tool: ouroboros_interview
Arguments:
initial_context: <user's topic or idea>
cwd: <current working directory>
Returns a session ID and the first question.
For each question from MCP, apply the routing paths below:
Parent-session question handoff:
If an MCP response includes meta.status="parent_question_required" or
meta.ask_user_directly=true, treat it as a normal interview continuation,
not as an MCP/provider/tool failure. Do not tell the user MCP failed, do
not expose reason_code, and do not retry the MCP question generator. Ask
exactly one natural Socratic clarification question yourself, using the same
routing judgement as any other interview turn. Save the exact user-facing
question text. When the user answers, call:
Tool: ouroboros_interview
Arguments:
session_id: <meta.session_id>
answer: <user answer>
last_question: <exact question you asked the user>
last_question is required on this path so MCP can persist the real
transcript even though the parent session generated the question.
Milestone lateral-review dispatch:
If an MCP response includes meta.lateral_review_recommended=true, treat it
as a required lightweight subagent review for that turn. The interview just
crossed an ambiguity milestone such as initial -> progress,
progress -> refined, or refined -> ready, which is exactly when hidden
assumptions tend to matter.
Before answering or asking the returned question:
ouroboros_lateral_think with meta.lateral_review_tool_args when
present. If only the legacy advisory fields are present, call it with
personas=["researcher","contrarian","simplifier"], a problem context
containing the current interview session/milestone/question, and a current
approach describing the next interview-routing decision.The MCP interview tool is still the question generator and source of persistent state. Lateral review is a main-session assist layer: it helps the user feel supported, but it does not by itself change requirements or mark the interview complete.
Main-session direct-answer assistance: Use lateral review frequently when the main session would otherwise answer the MCP question directly or compress the user's free-text into a decision. This is the supported "deep research style" experience for interviews: the user should see that multiple perspectives are helping, while the final prompt stays easy to answer.
Trigger a lightweight ouroboros_lateral_think call before continuing when
any of these are true:
Prefer personas=["researcher","contrarian","simplifier"] for this
assist. Add architect when the answer changes system shape or ownership.
Summarize the result as 2-3 concrete options or one recommended answer draft,
then let the user approve, tweak, or switch to auto.
PATH 1 — Code Answer (describe current state from codebase): When the question asks about existing tech stack, frameworks, dependencies, current patterns, architecture, or file structure:
inspect_code capability to find the factual answerPATH 1a — Auto-confirm (high-confidence factual, no user block): When ALL of the following are true:
pyproject.toml, package.json, Dockerfile, go.mod, .env.example)Then:
[from-code][auto-confirmed] prefix"ℹ️ Auto-confirmed: Python 3.12, FastAPI framework (pyproject.toml)"Examples of auto-confirmable facts:
PATH 1b — Code Confirmation (medium/low confidence, user confirms): When the codebase has relevant information but confidence is not high enough for auto-confirm (inferred from patterns, multiple candidates, or no manifest match):
ask_user capability:
{
"questions": [{
"question": "MCP asks: What auth method does the project use?\n\nI found: JWT-based auth in src/auth/jwt.py\n\nIs this correct?",
"header": "Q<N> — Code Confirmation",
"options": [
{"label": "Yes, correct", "description": "Use this as the answer"},
{"label": "No, let me correct", "description": "I'll provide the right answer"}
],
"multiSelect": false
}]
}
[from-code] when sending to MCP[from-code] and do not apply the Refine gate. Increment the
auto-confirm counter (see Dialectic Rhythm Guard below).ask_user capability to collect the corrected answer as free text:
{
"questions": [{
"question": "What should I send instead for this MCP question?\n\nMCP asks: What auth method does the project use?\n\nInclude any reasoning, constraints, or scope that should be preserved.",
"header": "Q<N> — Correction"
}]
}
[from-user][refined] (the
human is now the source of the corrected answer).[from-user][refined].PATH 2 — Human Judgment (decisions only humans can make): When the question asks about goals, vision, acceptance criteria, business logic, preferences, tradeoffs, scope, or desired behavior for NEW features:
ask_user capability with suggested options[from-user] when sending to MCPPATH 3 — Code + Judgment (facts exist but interpretation needed): When code contains relevant facts BUT the question also requires judgment (e.g., "I see a saga pattern in orders/. Should payments use the same?"):
inspect_code capability to read relevant code first[from-user] (human made the decision)PATH 4 — Research Interlude (external knowledge needed): When the question asks about third-party APIs, pricing models, library capabilities, version compatibility, security advisories, or industry standards that are NOT answerable from the local codebase:
web_research capability to gather external informationask_user capability
(same pattern as PATH 1, but with web sources instead of code):
{
"questions": [{
"question": "MCP asks: What rate limits does the Stripe API have?\n\nI found: Stripe allows 100 read ops/sec and 25 write ops/sec in live mode.\n\nIs this correct?",
"header": "Q<N> — Research Confirmation",
"options": [
{"label": "Yes, correct", "description": "Use this as the answer"},
{"label": "No, let me correct", "description": "I'll provide the right answer"}
],
"multiSelect": false
}]
}
[from-research] when sending to MCP[from-research] and do not apply the Refine gate. Increment the
auto-confirm counter (see Dialectic Rhythm Guard below).ask_user capability to collect the corrected answer as free text:
{
"questions": [{
"question": "What should I send instead for this MCP question?\n\nMCP asks: What rate limits does the Stripe API have?\n\nInclude any source correction, reasoning, constraints, or scope that should be preserved.",
"header": "Q<N> — Research Correction"
}]
}
[from-user][refined] (the
human is now the source of the corrected answer).[from-user][refined].When in doubt, use PATH 2. It's safer to ask the user than to guess.
Send the answer back to MCP:
Payload format — preserve the user's reasoning, do NOT compress to one line. MCP cannot read code, browse the web, or call tools. The text you send is the only context MCP has when generating the next question. A one-line answer collapses the user's reasoning, constraints, and scope decisions into a label, which degrades both the next question's quality and the ambiguity scoring. Send the user's full reasoning, structured.
Single-line answers are OK only for PATH 1a auto-confirmed facts, PATH 1b / PATH 4 pre-built option confirmations where the factual answer is already explicit, and short PATH 2 answers that have no reasoning or constraints attached (e.g., "Yes" / "No" / "Python 3.12"). User corrections, free-text reasoning, constraints, or scope decisions must be sent as the multi-section payload below after the Refine gate.
Tool: ouroboros_interview
Arguments:
session_id: <session ID>
answer: |
[from-user][refined]
Decision: Stripe Billing.
Reasoning:
- Subscription is the core business model.
- Stripe bundles invoice/dunning/tax — avoids building those.
Constraints (user-stated):
- 30% Korean MAU, KRW required.
- Revenue recognition automation OUT OF SCOPE this quarter.
Out of scope (user-stated):
- Refund policy changes, tax-invoice issuance.
Codebase context (main session verified):
- src/billing/ does not exist yet.
- src/payments/toss_adapter.py is one-shot KRW only.
Short-answer cases (single-line OK):
"[from-code][auto-confirmed] Python 3.12, FastAPI (pyproject.toml)"
"[from-code] JWT-based auth in src/auth/jwt.py"
"[from-research] Stripe allows 100 read ops/sec and 25 write ops/sec in live mode"
"[from-user] Yes"
Append [refined] to an existing valid prefix ([from-code],
[from-user], or [from-research]) only when the answer has been through
the Refine gate (see Step 4). MCP records the answer, generates the next
question, and returns it.
Refine before forwarding (free-text answers only):
When the user gives a free-text answer that carries reasoning, constraints,
or scope decisions, do NOT forward it to MCP unmodified and do NOT compress
it to a label. Structure it into the multi-section payload above, then ask
the user a single ask_user capability to confirm nothing is lost:
{
"questions": [{
"question": "I structured your answer as follows before sending it to MCP:\n\n<multi-section payload>\n\nIs anything missing or misrepresented?",
"header": "Refine — preserve the structure of your answer",
"options": [
{"label": "Send as-is", "description": "The structure captures my answer faithfully"},
{"label": "Add to Constraints", "description": "I want to add a constraint I forgot"},
{"label": "Add to Out of scope", "description": "I want to mark something explicitly out of scope"},
{"label": "Add context", "description": "I want to add reasoning, code context, or research context"},
{"label": "Rewrite", "description": "Let me re-state the answer"}
],
"multiSelect": false
}]
}
The Refine gate replaces "compress to one line" with "preserve the user's reasoning, surface anything missing." It is skipped for:
Exception — Restate corrections never skip Refine, regardless of length.
Any free-text follow-up collected by the Step 9 Restate gate
("Adjust wording" / "Missing scope") must go through Refine before being
forwarded to MCP. Even a short correction like
"Exclude retry scheduling from the seed." carries scope/boundary
information that MCP needs in structured form during the reopen call, so
the short-PATH-2 exemption above does NOT apply to Restate corrections.
A single-line Restate correction that bypasses Refine would forward
[from-user] instead of [from-user][refined] and would not trigger the
last_question reopen, leaving MCP on stale pre-correction state when
the seed is generated.
Refine-passed answers count as direct user judgment — they reset the Dialectic Rhythm Guard counter to 0 (see below).
If the user picks "Add to Constraints", "Add to Out of scope", "Add context",
or "Rewrite", do not infer the missing text from the option label. Immediately
use the ask_user capability for one follow-up to collect the exact text:
{
"questions": [{
"question": "What text should I add or change before sending this to MCP?\n\nCurrent structured answer:\n\n<multi-section payload>",
"header": "Refine — Missing Text"
}]
}
Apply the follow-up text to the structured payload, then ask the Refine gate
once more. Do not send the payload to MCP while the user is still telling
you that required text is missing or the answer should be rewritten. If the
second Refine response again says "Add to Constraints", "Add to Out of
scope", "Add context", or "Rewrite", ask a targeted PATH 2 follow-up for the
exact missing text and withhold the MCP answer until the user either
supplies that text or explicitly accepts the structured payload. The
Add context option is handled identically to the other three on the
second pass — never infer omitted content from the option label, and prefer
stopping over forwarding a payload the user has identified as incomplete.
Mark the answer as Refine-passed:
Append [refined] to the prefix when sending the structured payload to
MCP (e.g., [from-user][refined]). MCP treats refined answers as
high-confidence ground truth for ambiguity scoring.
Keep a visible ambiguity ledger: Track independent ambiguity tracks (scope, constraints, outputs, verification). Do NOT let the interview collapse onto a single subtopic.
Repeat steps 2-6 until the user says "done" or MCP signals seed-ready.
Seed-ready Acceptance Guard:
When MCP signals seed-ready, do NOT relay completion blindly. Before
announcing completion or suggesting ooo seed, apply the canonical Seed
Closer criteria from src/ouroboros/agents/seed-closer.md as the single
source of truth for closure readiness. Run the check from the main session's
perspective, including any code, research, or brownfield context MCP did not
see.
If any material decision remains unresolved, do not announce seed-ready.
If the local challenge finds a material gap, explicitly override the MCP
signal: "MCP says seed-ready, but I am not accepting it yet because <gap>."
Explain the gap briefly and ask the single highest-impact follow-up question,
routed through PATH 2 or PATH 3 as appropriate.
Restate gate (only after Seed-ready Acceptance Guard passes):
Once the Acceptance Guard passes, do not jump straight to ooo seed.
First restate the agreed goal as a single sentence and ask the user to
confirm it captures the decision. This is the one place where compression
to a single line is the goal — every other answer in the interview was
sent to MCP in full multi-section form (see Step 3), and now we collapse
the accumulated agreement into a one-line goal that another person could
read and arrive at the same outcome.
{
"questions": [{
"question": "Based on the answers we agreed on, here is a one-sentence restatement of the goal:\n\n goal: <one-sentence restatement>\n\nIf someone else read only this line, would they arrive at the same outcome you have in mind?",
"header": "Restate — one-line goal before seed",
"options": [
{"label": "Yes, generate seed", "description": "The line captures the goal; proceed to ooo seed"},
{"label": "Adjust wording", "description": "The intent is right but I want to change words"},
{"label": "Missing scope", "description": "A condition or boundary is missing from the line"}
],
"multiSelect": false
}]
}
Only after the user accepts the restated line do you suggest ooo seed.
If the user picks "Adjust wording", immediately use the ask_user capability
to collect the replacement wording:
{
"questions": [{
"question": "How should the one-sentence goal be worded instead?\n\nCurrent line:\n goal: <one-sentence restatement>",
"header": "Restate — Wording"
}]
}
If the user picks "Missing scope", immediately use the ask_user capability
to collect the missing condition or boundary:
{
"questions": [{
"question": "What scope, condition, or boundary is missing from the one-sentence goal?\n\nCurrent line:\n goal: <one-sentence restatement>",
"header": "Restate — Scope"
}]
}
Treat the follow-up text as a real interview correction, not a local-only
wording tweak. Route the follow-up text through the Refine gate before
forwarding it. The Step 4 short-PATH-2 skip rule does NOT apply here,
even if the correction is a single sentence — a bare reply like
"Exclude retry scheduling from the seed." still encodes a boundary
decision that must reach MCP as [from-user][refined] with the reopen
last_question; sending it as [from-user] would leave MCP on the stale
pre-correction state. Then build the same structured multi-section
payload from Step 3 using the canonical five-section schema —
[from-user][refined], preserving the corrected goal line and the user's
stated wording or missing scope. Because this is a post-seed-ready follow-up
that MCP did not generate, call ouroboros_interview with both the
structured answer and last_question set to the exact local Restate
follow-up prompt you asked (for example, the "How should the one-sentence
goal be worded instead?" or "What scope, condition, or boundary is missing?"
question). Without last_question, the handler must reject the reopen rather
than attach the correction to a stale MCP question. Then return to Step 7 so
MCP can update its interview state and the Seed-ready Acceptance Guard can
run again against the updated state. Do not proceed directly to ooo seed
from the stale pre-correction MCP state.After MCP returns seed-ready again and the Acceptance Guard still passes, ask the Restate gate once more with the corrected goal line. Do not loop more than twice; if alignment is not reached, route back to PATH 2 with a targeted question instead of forcing a goal line.
Prefer stopping over over-interviewing:
When the Restate gate passes, suggest ooo seed.
After completion, suggest the next step:
📍 Next: ooo seed to crystallize these requirements into a specification
Track consecutive non-user answers (PATH 1a auto-confirms, PATH 1b code confirmations, and PATH 4 research confirmations). If 3 consecutive questions were answered without direct user judgment (PATH 1a, 1b, or PATH 4), the next question MUST be routed to PATH 2 (directly to user), even if it appears code- or research-answerable.
This preserves the Socratic dialectic rhythm — the interview is with the human, not the codebase or external docs. Auto-confirmed answers especially need this guard: if the AI answers too many questions on its own, the user loses awareness of what the AI is assuming about their project.
Reset the counter whenever user answers directly (PATH 2 or PATH 3), or when a
PATH 1b / PATH 4 correction is routed through the Refine gate and sent as
[from-user][refined]. Only accepted code/research confirmations advance the
non-user streak.
If MCP returns is_error=true with meta.recoverable=true:
ouroboros_interview(session_id=...) to resume (max 2 retries).
State (including any recorded answers) is persisted before the error,
so resuming will not lose progress.Special case — meta.reason == "initial_context_too_large": When the
response carries this meta.reason (with meta.recoverable=true and
is_error=false — the wire success/failure axis is intentionally not
flipped, to keep existing callers like the auto driver working), the text
body is a meta-directive asking you to re-send a shorter context — it is
NOT an interview question. Do not route it through the active runtime's ask_user capability.
Instead, produce a concise summary of the original initial_context
(≤ meta.max_chars characters; covers goal, constraints, success criteria)
and re-call ouroboros_interview with session_id=<from meta> and the
summary as answer. The next response will contain the real first question.
Advantages of MCP mode: State persists to disk, ambiguity scoring, direct ooo seed integration via session ID. Code-enriched confirmation questions reduce user burden — only human-judgment questions require user input.
If the MCP tool is NOT available, fall back to agent-based interview:
src/ouroboros/agents/socratic-interviewer.md and adopt that roleinspect_code capability to check for config files (pyproject.toml, package.json, go.mod, etc.). If found, inspect key files and incorporate findings into your questions as confirmation-style ("I see X. Should I assume Y?") rather than open-ended discovery ("Do you have X?")ask_user capability with contextually relevant suggested answers (same format as Path A step 2)inspect_code and web_research capabilities to explore further context if neededooo seed.
In fallback mode there is no MCP state to refresh, so if the user picks
"Adjust wording" or "Missing scope", ask the same follow-up questions from
Step 9, apply the correction directly to the local interview ledger and
one-sentence goal, rerun the Seed-ready Acceptance Guard locally, and ask the
Restate gate again with the corrected goal line. Do not try to "send it back
to MCP" in Path B; the conversation context is the source of truth.📍 Next: format:
📍 Next: ooo seed to crystallize these requirements into a specificationMCP (question generator) is ONLY a questioner:
You (main session) are a Socratic facilitator:
src/ouroboros/agents/socratic-interviewer.md to understand the interview methodologyinspect_code capability to scan the codebase for answering MCP questionsooo seedUser: ooo interview Add payment module to existing project
MCP Q1: "Is this a greenfield or brownfield project?"
→ PATH 1a: exact match in pyproject.toml + src/ directory
→ ℹ️ Auto-confirmed: Brownfield, Python 3.12 / FastAPI (pyproject.toml)
→ [from-code][auto-confirmed] sent to MCP (counter: 1)
MCP Q2: "What payment provider will you use?"
→ PATH 2: human decision — no code can answer this
→ User: "Stripe"
→ [from-user] sent to MCP (counter reset to 0)
MCP Q3: "What authentication method does the project use?"
→ PATH 1b: found src/auth/jwt.py but inferred (not manifest)
→ "I found JWT-based auth in src/auth/jwt.py. Is this correct?"
→ User: "Yes, correct"
→ [from-code] sent to MCP (counter: 1)
MCP Q4: "How should payment failures affect order state?"
→ PATH 2: design decision
→ User: "Saga pattern for rollback"
→ Refine gate structures the answer
→ User: "Add to Out of scope"
→ Follow-up asks for exact missing text
→ User: "Do not build automatic retry scheduling yet"
→ Refine gate runs once more, then [from-user][refined] sent to MCP (counter reset to 0)
MCP Q5: "What are the acceptance criteria for this feature?"
→ PATH 2: requires human judgment
→ User: "Successful Stripe charge, webhook handling, refund support"
→ Refine gate passes; [from-user][refined] sent to MCP
MCP signals seed-ready; Acceptance Guard passes
→ Restate: "Add Stripe payments with charges, webhooks, refunds, and failed-payment rollback."
→ User: "Missing scope"
→ Follow-up asks for exact missing scope
→ User: "Exclude retry scheduling from the seed."
→ Refine gate structures the restate correction
→ [from-user][refined] restate correction sent to MCP; return to Step 7/Seed-ready guard
→ MCP signals seed-ready again; Acceptance Guard still passes
→ Restate again: "Add Stripe payments with charges, webhooks, refunds, failed-payment rollback, and no retry scheduling."
→ User: "Yes, generate seed"
📍 Next: `ooo seed` to crystallize these requirements into a specification
After interview completion, use ooo seed to generate the Seed specification.