explore

name	explore
description	Explore ideas, think through approaches, and route insights to the right artifacts.
allowed-tools	Read, Write, Glob, Grep, Task, AskUserQuestion, Skill
argument-hint	[topic]

STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► EXPLORING                                  ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:explore — Idea Exploration

You are running the explore skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.

This skill runs inline (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.

CRITICAL: Agent type rule — When spawning ANY research or analysis Task(), ALWAYS use subagent_type: "pbr:researcher". NEVER use general-purpose, Explore, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.

---

References

• references/questioning.md — Questioning philosophy, progressive depth layers, Socratic patterns, anti-patterns (checklist walking, corporate speak)
• references/ui-brand.md — Status symbols, banners, checkpoint boxes, progress display

---

Context Budget

Reference: skills/shared/context-budget.md for the universal orchestrator rules. Reference: skills/shared/agent-type-resolution.md for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• Minimize file reads — this is a thinking skill, not a code analysis skill
• Delegate deep research to a researcher subagent if investigation exceeds the read threshold:
  • At context_window_tokens < 500000 (200k model): delegate after 3-4 file reads
  • At context_window_tokens >= 500000 (1M model): delegate after 12 file reads Check context_window_tokens in .planning/config.json to determine which limit applies.

---

How /pbr:explore Differs from /pbr:discuss-phase

	/pbr:discuss-phase	/pbr:explore
Purpose	Make decisions for a phase	Discover what you actually want
Structure	Pre-computed gray areas with options	Open-ended Socratic conversation
Requires	Phase number	Nothing
Output	CONTEXT.md (locked decisions)	Routes to the right artifact
Feels like	Making decisions	Thinking with a partner

---

Invocation

• /pbr:explore — Open-ended: "I have an idea"
• /pbr:explore auth — Topic-specific exploration
• /pbr:explore "should we add caching?" — Specific question

Parse $ARGUMENTS for an optional topic. If provided, use it to seed the opening question. If empty, start fully open-ended.

---

Pre-Conversation Context Loader

Reference: skills/shared/context-loader-task.md for the full briefing Task() pattern.

Only runs if .planning/ directory exists. Fresh explores with no project skip this entirely.

When a project exists, spawn a briefing Task() per the context-loader-task pattern with skill_purpose = "exploring new ideas". If a topic was provided, use the topic-scoped variation with that topic.

Use the briefing to inform your conversation — reference existing decisions, avoid re-litigating settled questions, and connect new ideas to the existing project structure.

---

Conversation Design

The conversation is Socratic, not extractive. You are a thinking partner, not an interviewer.

Principles

1. Open with curiosity. Start with "What are you thinking about?" or "What's on your mind?" — not "Please describe the feature you want."

2. Follow their energy. Dig into what excites or concerns them. If they light up about a technical approach, explore it. If they hesitate, probe why.

3. Surface implications. "If you go with X, that usually means Y and Z. Is that intentional?" Connect their idea to downstream consequences they may not see yet.

4. Challenge with alternatives. "You mentioned X, but have you considered Y?" Don't be adversarial — offer genuine alternatives that might fit better.

5. Present trade-offs, not options. "A gives you speed but locks you into a vendor. B is slower but keeps options open." Frame choices as trade-offs with real consequences, not a menu.

6. Know when to research. "I'm not sure about the best approach here. Want me to research it?" Don't fake knowledge — admit gaps and offer to investigate.

7. Don't rush to outputs. Explore until understanding is genuinely deep. The user will know when they're ready to wrap up.

Domain-Aware Probing

Reference skills/shared/domain-probes.md for technology-specific follow-up questions. When the user mentions a domain (auth, caching, search, etc.), pick the 2-3 most relevant probes from that domain's table. Do NOT run through the table as a checklist.

Conversation Starters by Invocation

Invocation	Opening
/pbr:explore	"What are you thinking about?"
/pbr:explore auth	"What's your thinking on auth? Are you starting from scratch or rethinking something?"
/pbr:explore "should we add caching?"	"Caching for what specifically? What's feeling slow or what do you expect to be slow?"

---

Upfront Research Delegation

When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to pbr:researcher agents rather than doing inline research.

Detection: If $ARGUMENTS contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.

Pattern: Spawn one or more pbr:researcher agents in parallel, then synthesize their findings inline:

Task({
  subagent_type: "pbr:researcher",
  prompt: "<research_assignment>
    Topic: {specific research question from user's request}
    Output: Return findings as structured markdown in your response.
    Mode: external-research

    {detailed research instructions}
  </research_assignment>"
})

After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.

---

Mid-Conversation Research

When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.

CRITICAL -- DO NOT SKIP: Present the following choice to the user via AskUserQuestion before proceeding: Ask the user using the yes-no pattern from skills/shared/gate-prompts.md: question: "I'm not sure about the best approach for {topic}. Research it now?" options: - label: "Research now" description: "Spawn a researcher agent to investigate" - label: "Save for later" description: "Add as a research question for future investigation"

If research now:

Display to the user: ◆ Spawning researcher...

Learnings injection (opt-in): Check for relevant tech stack learnings:

pbr-tools learnings query --tags "stack,tech,friction" 2>/dev/null

If non-empty JSON array returned:

• Write to temp file: pbr-tools learnings query --tags "stack,tech,friction" > /tmp/pbr-learnings-$$.md
• Note path as {learnings_temp_path}; add as item 3 in the researcher's files_to_read block below

If no learnings or command fails: omit the extra files_to_read entry.

Task({
  subagent_type: "pbr:researcher",
  prompt: "<files_to_read>
    CRITICAL: Read these files BEFORE any other action:
    1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
    2. .planning/STATE.md — current project state (if exists)
    {if learnings_temp_path exists}3. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
  </files_to_read>
  <research_assignment>
    Topic: {specific research question}
    Output file: .planning/research/{topic-slug}.md (generate topic-slug via: pbr-tools slug-generate "{topic}")
    Mode: project-research

    Research this specific question: {the question}

    Write findings to the output file.
  </research_assignment>"
})

If {learnings_temp_path} was produced above, replace {if...}{/if} with the actual line. If no learnings were found, omit item 3 entirely.

After the researcher completes, check for completion markers in the Task() output:

• If ## RESEARCH COMPLETE is present: proceed normally
• If ## RESEARCH BLOCKED is present: display the blocker reason and offer to retry: ⚠ Research blocked: {reason}. Try a different angle or continue without research.

Display: ✓ Research complete — results in .planning/research/{topic-slug}.md

Then:

• Read ONLY the frontmatter and summary section of the research file (not the full document)
• Incorporate the 2-3 key findings into the conversation
• Main context gets ~200 tokens of research insight, not the full document

If save for later:

• Note it as a research question to include in output routing

---

Optional: Thinking Partner Chain

If the user is weighing 2+ approaches with genuine trade-offs (not just preference), and the exploration has surfaced enough context to make the analysis meaningful, offer to invoke the thinking partner:

"This looks like a multi-dimensional trade-off. Want me to run it through structured reasoning to sharpen the comparison?"

If yes: Skill({ skill: "thinking-partner", args: "{concise problem statement with the 2-3 options and their trade-offs}" })

If no: Continue to output routing.

Do NOT chain thinking-partner for:

• Binary yes/no decisions
• Procedural choices with a clear best option
• Preferences with no downstream consequences

---

Context Pressure Awareness

After approximately 10 exchanges or when the conversation has been substantial, mention:

"We've been exploring for a while. Want to wrap up with outputs, or keep going?"

Don't force a conclusion — some explorations legitimately need extended conversation. But surface the option so the user can choose.

---

Output Routing

This is the key innovation of /pbr:explore. At conversation end, the agent summarizes key insights and routes them to the right artifacts.

Step 1: Summarize

Provide a concise summary of the key insights from the conversation:

• What was the core idea or question?
• What did we discover or decide?
• What remains uncertain?

Step 2: Propose Outputs

Suggest specific outputs with reasoning. Present no more than 4 suggestions — focus on what matters most.

Output Type	When to Suggest	Where It Goes
Todo	Small, actionable item discovered	.planning/todos/pending/{id}.md
Requirement	New project feature identified	Append to REQUIREMENTS.md with REQ-ID
Phase decision	Clarifies an existing phase	Write/append to phase CONTEXT.md
Research question	Needs deeper investigation	.planning/research/questions.md
New phase	Big enough for its own phase	Append to ROADMAP.md
Note	Not actionable yet, worth remembering	.planning/notes/{YYYY-MM-DD}-{slug}.md
Quick capture	One-liner idea, no context needed	Suggest /pbr:note <text> to the user
Seed	Idea with trigger conditions	.planning/seeds/SEED-{NNN}-{slug}.md

Format for proposals:

Based on our conversation, here's what I'd suggest capturing:

1. **Todo**: "{title}" — {why this is a todo and not something bigger}
2. **Seed**: "{title}" — {why this should wait for a trigger condition}
3. **Research question**: "{question}" — {why we need to investigate this}

Want to adjust, add, or remove any of these?

Step 3: Confirm

CRITICAL -- DO NOT SKIP: Present the following choice to the user via AskUserQuestion before proceeding: Use the output-routing pattern from skills/shared/gate-prompts.md: question: "How do you want to handle these proposed outputs?"

Handle responses:

• "Approve all": Create all suggested artifacts (proceed to Step 4)
• "Adjust": The user wants to modify proposals. Have a freeform conversation to adjust, then re-present with another AskUserQuestion.
• "Add more": The user has additional outputs. Gather them conversationally, add to the list, then re-present.
• "Skip": End the session without creating artifacts. This is fine — sometimes exploring is enough.

Do NOT create any artifacts until the user selects "Approve all" on the final set.

Step 4: Create Artifacts

CRITICAL (no hook) -- DO NOT SKIP: Create target directories and write artifact files.

Directory creation: Before writing any artifact, ensure the target directory exists. Create .planning/notes/, .planning/seeds/, .planning/research/, or .planning/todos/pending/ as needed if they don't already exist.

Create only the approved artifacts. A single explore session can produce multiple outputs across different types.

Step 5: Completion

After creating artifacts (or if user chose "Skip"), display:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓                     ║
╚══════════════════════════════════════════════════════════════╝

{count} artifacts created: {list of artifact types}



╔══════════════════════════════════════════════════════════════╗
║  ▶ NEXT UP                                                   ║
╚══════════════════════════════════════════════════════════════╝

**{Primary route based on what was created}**

{Smart routing — pick the most relevant primary command:}
- If a todo was created: **Manage tasks** → `/pbr:todo`
- If a phase decision was captured: **Plan the phase** → `/pbr:plan-phase {N}`
- If a new phase was added: **Discuss the new phase** → `/pbr:discuss-phase {N}`
- If research questions were logged: **Plan with research** → `/pbr:plan-phase {N}`
- If current milestone is complete (STATE.md status is "milestone-complete"): **Start next milestone** → `/pbr:new-milestone`
- Default: **See project status** → `/pbr:progress`

`{primary command}`

<sub>`/clear` first → fresh context window</sub>



**Also available:**
- `/pbr:progress` — see project status
- `/pbr:continue` — execute next logical step
- `/pbr:new-milestone` — start a new milestone with new phases

---

Output Formats

Todo

CRITICAL: Write the todo file NOW. Do not skip this step.

Write to .planning/todos/pending/{NNN}-{slug}.md where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan both .planning/todos/pending/ and .planning/todos/done/ for the highest existing number, increment by 1, and zero-pad. Generate slug via CLI: pbr-tools slug-generate "{todo title}". Follow the format used by the existing todo skill.

Requirement

Append to .planning/REQUIREMENTS.md with the next available REQ-ID in the appropriate category. If the category doesn't exist, create it.

Phase Decision

Append to .planning/phases/{NN}-{slug}/CONTEXT.md. If CONTEXT.md doesn't exist for that phase, create it with the standard header. Mark the decision as coming from /pbr:explore.

Research Question

Append to .planning/research/questions.md. Create the file if it doesn't exist:

# Research Questions

Questions identified during exploration that need deeper investigation.

## Open

- [ ] {Question} — Source: /pbr:explore session ({date})

## Answered

(none yet)

New Phase

Append to .planning/ROADMAP.md following the existing phase format. Assign the next available phase number.

Note

CRITICAL: Write the note file NOW. Do not skip this step.

Write to .planning/notes/{YYYY-MM-DD}-{slug}.md where the date prefix is today's date in ISO format. Generate slug via CLI: pbr-tools slug-generate "{note title}". Scan .planning/notes/ to avoid filename collisions — if a file with the same date and slug exists, append -2 (or increment).

---
created: {ISO date}
source: "/pbr:explore session"
topic: "{topic}"
---
# {Title}

{Content from the conversation — key insights, reasoning, context}

Seed

CRITICAL: Write the seed file NOW. Do not skip this step.

Write to .planning/seeds/SEED-{NNN}-{slug}.md where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan .planning/seeds/ for the highest existing SEED number, increment by 1, and zero-pad. Generate slug via CLI: pbr-tools slug-generate "{seed title}".

---
id: SEED-{NNN}
status: dormant
planted: {ISO date}
trigger: "{phase-slug}"
scope_estimate: "small|medium|large"
source: "/pbr:explore session"
---
# {Title}

## Context
{Why this idea came up}

## Breadcrumbs
{Related phases, technologies, user preferences}

---

Git Integration

Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.

If planning.commit_docs: true in config.json, commit created artifacts:

docs(planning): capture explore session outputs

Stage only the files created during this session. Do not stage unrelated changes.

---

Error Handling

Reference: skills/shared/error-reporting.md for branded error output patterns.

Researcher agent fails

If a mid-conversation researcher Task() fails, display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Research agent failed for topic: {topic}.

**To fix:** Continue the conversation without research, or try `/pbr:explore` again with a more specific topic.

Context loader fails

If the briefing Task() fails:

• Display: ⚠ Context loading failed. Proceeding without project context.
• Continue with the exploration — the conversation can still be valuable without project context.

---

Anti-Patterns

Additionally for this skill:

1. DO NOT act like an interviewer — be a thinking partner
2. DO NOT cycle through a checklist of questions
3. DO NOT rush to outputs before understanding is deep
4. DO NOT auto-research without asking (unless config mode is autonomous)
5. DO NOT present more than 4 output suggestions — focus on what matters
6. DO NOT create artifacts the user didn't approve
7. DO NOT re-litigate decisions that are already locked in CONTEXT.md
8. DO NOT force the user to produce outputs — sometimes exploring is enough