msd-core/gsd-core/workflows/explore.md

Socratic ideation workflow. Guides the developer through exploring an idea via probing questions, offers mid-conversation research when useful, then routes crystallized outputs to GSD artifacts.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting.

@/.claude/gsd-core/references/questioning.md @/.claude/gsd-core/references/domain-probes.md </required_reading>

<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):

• gsd-phase-researcher — Researches specific questions and returns concise findings </available_agent_types>

Step 1: Open the conversation

If a topic was provided, acknowledge it and begin exploring:

## Explore: {topic}

Let's think through this together. I'll ask questions to help clarify the idea
before we commit to any artifacts.

If no topic, ask:

## Explore

What's on your mind? This could be a feature idea, an architectural question,
a problem you're trying to solve, or something you're not sure about yet.

Step 2: Socratic conversation (2-5 exchanges)

Guide the conversation using principles from questioning.md and domain-probes.md:

• Ask one question at a time (never a list of questions)
• Questions should probe: constraints, tradeoffs, users, scope, dependencies, risks
• Use domain-specific probes contextually when the topic touches a known domain
• Listen for signals: "or" / "versus" / "tradeoff" indicate competing priorities worth exploring
• Reflect back what you hear to confirm understanding before moving forward

Conversation should feel natural, not formulaic. Avoid rigid sequences. Follow the developer's energy — if they're excited about one aspect, go deeper there.

Step 3: Mid-conversation research offer (after 2-3 exchanges)

If the conversation surfaces factual questions, technology comparisons, or unknowns that research could resolve, offer:

This touches on [specific question]. Want me to do a quick research pass before we continue?
This would take ~30 seconds and might surface useful context.

[Yes, research this] / [No, let's keep exploring]

If yes, spawn a research agent:

Print: ◆ Spawning explorer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)

Agent(
  prompt="Quick research: {specific_question}. Return 3-5 key findings, no more than 200 words.",
  subagent_type="gsd-phase-researcher"
)

ORCHESTRATOR RULE — CODEX RUNTIME: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.

Share findings and continue the conversation.

If the topic doesn't warrant research, skip this step entirely. Don't force it.

Step 4: Crystallize outputs (after 3-6 exchanges)

When the conversation reaches natural conclusions or the developer signals readiness, propose outputs. Analyze the conversation to identify what was discussed and suggest up to 4 outputs from:

Type	Destination	When to suggest
Note	.planning/notes/{slug}.md	Observations, context, decisions worth remembering
Todo	.planning/todos/pending/{slug}.md	Concrete actionable tasks identified
Seed	.planning/seeds/{slug}.md	Forward-looking ideas with trigger conditions
Research question	.planning/research/questions.md (append)	Open questions that need deeper investigation
Requirement	REQUIREMENTS.md (append)	Clear requirements that emerged from discussion
New phase	ROADMAP.md (append)	Scope large enough to warrant its own phase
Spike	/gsd:spike (invoke)	Feasibility uncertainty surfaced — "will this API work?", "can we do X?"
Sketch	/gsd:sketch (invoke)	Design direction unclear — "what should this look like?", "how should this feel?"

Present suggestions:

Based on our conversation, I'd suggest capturing:

1. **Note:** "Authentication strategy decisions" — your reasoning about JWT vs sessions
2. **Todo:** "Evaluate Passport.js vs custom middleware" — the comparison you want to do
3. **Seed:** "OAuth2 provider support" — trigger: when user management phase starts

Create these? You can select specific ones or modify them.

[Create all] / [Let me pick] / [Skip — just exploring]

Never write artifacts without explicit user selection.

Step 5: Write selected outputs

For each selected output, write the file:

• Notes: Create .planning/notes/{slug}.md with frontmatter (title, date, context)
• Todos: Create .planning/todos/pending/{slug}.md with frontmatter (title, date, priority)
• Seeds: Create .planning/seeds/{slug}.md with frontmatter (title, trigger_condition, planted_date)
• Research questions: Append to .planning/research/questions.md
• Requirements: Append to .planning/REQUIREMENTS.md with next available REQ ID
• Phases: Use existing /gsd-add-phase command via SlashCommand

Commit if commit_docs is enabled:

_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
gsd_run query commit "docs: capture exploration — {topic_slug}" --files {file_list}

Step 6: Close

## Exploration Complete

**Topic:** {topic}
**Outputs:** {count} artifact(s) created
{list of created files}

Continue exploring with `/gsd:explore` or start working with `/gsd:progress --next`.

<success_criteria>

• Socratic conversation follows questioning.md principles
• Questions asked one at a time, not in batches
• Research offered contextually (not forced)
• Up to 4 outputs proposed from conversation
• User explicitly selects which outputs to create
• Files written to correct destinations
• Commit respects commit_docs config </success_criteria>