!${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh explore 2>&1 || true

@.claude/shirabe-extensions/explore.md @.claude/shirabe-extensions/explore.local.md

Explore

Explore is the entry point for "I don't know what I need." It serves two roles: as a passive routing advisor (when Claude is auto-loaded and users need help picking a command), and as an active exploration workflow (when invoked via /explore).

Other skills own the work itself: /scope runs the tactical chain, /charter the strategic one, /execute drives a finished PLAN, and /work-on takes a single issue. Explore owns the question of which one receives the work, and it answers that question after the research rather than before it.

Writing style: Read skills/writing-style/SKILL.md for guidance.

Routing Guide

When a user isn't sure where to start, use this table to recommend a command. Every destination is something the author runs. None of them is a step inside a chain that a parent skill already sequences: a BRIEF, a PRD, a DESIGN, and a PLAN are hops inside /scope, and picking one of them as an entry point is the choice this skill stopped making. Those hops stay directly invocable once their own upstream is settled -- /design on an accepted PRD, /plan on an accepted DESIGN -- but an author in that position is not asking where to start, so no row below points at them.

Quick Decision Table

Three distinctions are gone from these two tables rather than re-pointed: "should I write a PRD or a design doc?", the pair that split "what should we build" from "how should we build it", and "what order do we build in?". Each one separated two hops of the same chain, and each mattered only while those hops were separately choosable. A BRIEF, a PRD, a DESIGN, and a PLAN are steps inside /scope, so all three questions now have one answer and take one row.

Complexity-Based Routing

Complexity is advisory, and only here. It answers "which command should I run?" before any exploration exists. Once an exploration has run, Phase 4 scores the accumulated findings, and nothing in this section feeds that scoring -- a second classification vocabulary inside the one routing surface would just disagree with it.

The Medium row is removed rather than re-pointed. Its recommendation was design then plan, and the case it described -- requirements settled, approach open -- was worth separating only while those two were separately choosable. A request that used to land on Medium reads as Complex here, and /explore decides whether it enters the chain at /scope or is small enough to file.

Detection Algorithm

Check from highest complexity down. Stop at the first YES.

1. Does the request reference project direction, multi-feature sequencing,
   or thesis validation?
   YES -> Strategic
   Boundary: if it's about one feature within an existing project -> Complex

2. Can the user clearly state both what to build and how?
   NO (the problem is unclear, or the approach is contested) -> Complex

3. Does a GitHub issue exist (or should one exist) with defined scope?
   YES -> Simple
   Boundary: if "done" is self-evident without acceptance criteria -> Trivial

4. Is the change self-evident and fire-and-forget?
   YES -> Trivial

5. Default -> Simple (file an issue and proceed)

Step 2 absorbs the old Medium question. Design decisions where reasonable people could disagree leave "how" unstated, which is a Complex answer now.

Crystallize Framework

Phase 4 scores the exploration's findings in two stages: what the exploration is -- four terminal outcomes no chain owns, plus "a chain" -- and then, for a chain, which entry point receives it. See references/quality/crystallize-framework.md for the candidacy preconditions, both scoreboards, and the tiebreakers. Loaded during Phase 4.

Exploration Workflow

When invoked as /explore, this skill drives a structured expansion-contraction loop. Fan out research agents on leads, converge findings with the user, repeat until ready, then decide what artifact type to produce.

Input Detection

From $ARGUMENTS:

1. Empty -- ask the user what they want to explore
2. Issue number (matches #?\d+ or org/repo#\d+) -- read the issue, check for needs-triage label, and derive topic from the issue title
3. Anything else -- use as the topic string, proceed to scope

For cross-repo issues (e.g., owner/repo#42), use gh commands:

gh issue view 42 --repo owner/repo --json title,body,labels

Context Resolution

0. Detect Execution Mode

Check $ARGUMENTS for --auto or --interactive flags. Also check for --max-rounds=N. If neither mode flag is present, read CLAUDE.md ## Execution Mode: header (values: auto or interactive, default: interactive).

In --auto mode, the agent never blocks on user input. At decision points, follow the research-first protocol in references/decision-protocol.md: gather evidence, form recommendation, follow it, document as a decision block. Track all decisions in key work/decisions.md.

Default max rounds in --auto: 3. Override with --max-rounds=N.

1. Detect Visibility

Read the repo's CLAUDE.md (or CLAUDE.local.md) for:

## Repo Visibility: Private

or

## Repo Visibility: Public

If not found, infer from path: private/ -> Private, public/ -> Public. Default to Private if unknown.

Visibility is immutable -- public repos must never accidentally include private references, even if a user passes --private. Flags can't override it.

After detecting visibility, load the appropriate content governance skill:

• Private repos: Read skills/private-content/SKILL.md
• Public repos: Read skills/public-content/SKILL.md

2. Detect Scope

Check $ARGUMENTS for --strategic or --tactical flags. If neither, read default from CLAUDE.md:

## Default Scope: Strategic

Default to Tactical if not found.

Scope sets how the research phases read the topic and how content governance applies. It puts no thumb on the crystallize scoreboard. --strategic is also a repo default read from CLAUDE.md, so letting it bias the outcome would pre-answer the router for every exploration in a strategic-default repo. An exploration launched strategic can land on /scope, and one launched tactical can land on /charter.

3. Log Context

Output before proceeding:

Exploring with [Private|Public] visibility in [Strategic|Tactical] scope...

Cross-Repo Issue Handling

When starting from an issue in a different repo than the working directory:

1. Read the issue via gh issue view <N> --repo <owner/repo>
2. Resolve visibility from the WORKING repo (where artifacts land), not the issue's repo
3. Visibility rule: public repos must not reference private issues in produced artifacts
4. Research agents may read the issue's repo for context, but the exploration's session explore-<topic> belongs to the working repo

Resume Logic

Resume is based on the keys of the topic's session, explore-<topic>. One call evaluates the rows top-to-bottom and prints the phase of the first match:

"${CLAUDE_PLUGIN_ROOT}/skills/explore/scripts/explore-state.sh" resume-phase <topic>

key work/crystallize.md exists                                     -> 5 (Produce)
key work/findings.md has "## Decision: Crystallize"                -> 4 (Crystallize)
key work/findings.md exists (no crystallize marker)                -> 3 (Converge)
keys research/r*_lead-* exist, no findings key                     -> 3 (Converge)
key work/scope.md exists                                           -> 2 (Discover)
none of these, on the topic branch                                 -> Phase 1 (Scope)
none of these, not on the topic branch                             -> Phase 0 (Setup)

The script prints none for the last two rows and for an absent or finished session; the branch decides between them. Before starting over on none, check for a key handoff/scope.md or handoff/charter.md in explore-<topic> (koto context exists): one means the exploration already ended in a handoff, and the author only needs the command that handoff names.

When resuming:

• Phase 3: Read all research keys and the findings key. Present accumulated results and ask whether to explore further or crystallize.
• Phase 4: The user decided to crystallize (marker in the findings key) but the crystallize key wasn't written. Re-run crystallize.
• Phase 5: Read the crystallize decision and proceed with handoff.

Workflow Phases

Phase 0: SETUP -> Phase 1: SCOPE -> Phase 2: DISCOVER -> Phase 3: CONVERGE --+
                                          ^                     |             |
                                          |      "explore       |             |
                                          +---- further" ------+             |
                                                                 "ready"      |
                                                                    |         |
                                                           Phase 4: CRYSTALLIZE
                                                                    |
                                                           Phase 5: PRODUCE

Phase Execution with Loop Management

Execute phases sequentially. After Phase 3, the orchestrator (this file) manages the discover-converge loop -- not the phase files.

Phase 0: Setup Read: references/phases/phase-0-setup.md

Phase 1: Scope Read: references/phases/phase-1-scope.md

Phase 2: Discover (Round N) Read: references/phases/phase-2-discover.md

On the first pass, N=1. On subsequent passes after "explore further," increment N.

Phase 3: Converge Read: references/phases/phase-3-converge.md

After Phase 3 completes, present the loop decision using AskUserQuestion following the pattern in ${CLAUDE_PLUGIN_ROOT}/references/decision-presentation.md.

Recommendation heuristic: If the convergence output surfaces significant gaps, open questions, or contradictions, recommend "Explore further." If findings are sufficient and no major gaps remain, recommend "Ready to decide."

Options:

1. "Explore further (Recommended)" or "Ready to decide (Recommended)" -- based on heuristic above
2. The other option, with a brief justification for why it ranks lower

Description field: Ground the recommendation in specific convergence output -- cite the gaps that remain or explain why coverage is sufficient.

If Explore further:

• Capture new leads from the user (informed by gaps and open questions from convergence)
• Update the scope key with the new leads for this round
• Return to Phase 2 with N incremented

If Ready to decide:

• Add ## Decision: Crystallize marker to the findings key
• Proceed to Phase 4

Phase 4: Crystallize Read: references/phases/phase-4-crystallize.md

Phase 5: Produce Read: references/phases/phase-5-produce.md

Session and Keys

/explore keeps its working state as keys in its own koto session, explore-<topic>, with a kebab-case topic, following ${CLAUDE_PLUGIN_ROOT}/references/skill-session-convention.md. It writes no file to the wip/ staging folder. Phase 0 opens the session once the branch exists (Step 0.1a) and before the first key is written:

"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" open explore <topic>

open attaches to a live explore-<topic> (an interrupted run, whose keys the resume rows read), replaces a finished one (a fresh run), or creates it. Any non-zero exit stops the run with the script's message: 127 or 69 means koto is missing or too old, and the skill never falls back to files.

Read a key with koto context get explore-<topic> <key>, test one with koto context exists explore-<topic> <key> (exit 0 present, 1 absent) and list a prefix with koto context list explore-<topic> --prefix <prefix>.

Writing a key. Assemble the content in a scratch directory, put it, and remove the directory:

dir=$("${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" scratch)
# write the content to "$dir/<name>", then:
"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" put explore-<topic> work/<name> "$dir/<name>"
rm -rf "$dir"

Editing a key the skill revises across rounds (scope, findings, decisions): get it into a fresh scratch directory (the command prints the file's path), edit that file, then put it back and remove the directory.

dir=$("${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" scratch)
"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" get explore-<topic> work/<name> "$dir"
# edit "$dir/<name>", then:
"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" put explore-<topic> work/<name> "$dir/<name>"
rm -rf "$dir"

Research agents never write keys: Phase 2 pins every lead's output to a file in a scratch directory and ingests it with the ingest-leads subcommand of explore-state.sh.

Closing. Phase 5 ends the session. The parent arms (/scope, /charter) run the finish-handoff subcommand of explore-state.sh, which clears the work/ and research/ keys and leaves the handoff for the parent to consume and close. Every other arm runs "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" close explore-<topic> done (after the inline child returns, for /decision and /comp), which keeps the keys readable. A run that stops before Phase 5 closes nothing, so its keys stay for the resume.

Decisions Key Format

The decisions key (work/decisions.md) tracks choices made during convergence rounds. It's created in Phase 3 on the first round that produces decisions, and appended to in subsequent rounds.

# Exploration Decisions: <topic>

## Round 1
- <decision>: <rationale>
- <decision>: <rationale>

## Round 2
- <decision>: <rationale>

Decisions include scope narrowing (areas eliminated), option elimination (approaches ruled out), priority choices (what matters most), and constraints accepted (trade-offs acknowledged). Each entry states what was decided and why in one or two lines.

Phase 4 reads this file to inform artifact type scoring. Phase 5 includes accumulated decisions in handoff artifacts. The file may not exist if no explicit decisions were made during exploration.

Reference Files