renzrollon/interlock/explore

Think deeply. Fan out when breadth is needed. Synthesize into understanding.

Explore is for thinking, not implementing. Read files, search code, investigate freely — but never write code and never implement a feature here. If asked to implement, say so and point at /interlock:spec. Writing OpenSpec artifacts or an explore brief is capturing thinking, not implementing, and is allowed.

Two modes

Conversational (default). A thinking partner. Ask the user which thread to pull when several look interesting. Iterate.

Autonomous. Activate on --autonomous, "no questions", "don't ask me", "pursue all threads", or when /interlock:spec invokes this skill. Then:

1. No user Q&A. No AskUserQuestion, no "which thread interests you?" menus. Open threads are work items, not questions.
2. Fan out on every thread. Each interesting thread or option gets a read-only investigator. Cap 2–5, merge in synthesis.
3. Prefer defaults. Ambiguous product intent → pick a reasonable default, record it under Assumptions Made and Pending Clarifications. Non-blocking. Every one of them is also a ledger row — see below.
4. Write the explore brief. Required exit criterion. Follow ${CLAUDE_PLUGIN_ROOT}/shared/EXPLORE-BRIEF.md. Path: .claude/handoff/explore-<slug>-<YYYYMMDD-HHMMSS>.md.
5. Close short. Brief path plus a 3–5 line summary. Do not re-dump findings into chat — they are in the brief.

Graph-first reconnaissance, before any fan-out

Follow Rule 0 of ${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md. If the graph exists, seed scopes then fan out:

interlock-graph query "<subsystem tokens>" --budget 1500
interlock-graph consumers <symbol-or-field>
interlock-graph path <A> <B>

Scope investigators by real module nodes and consumer lists. Each investigator: graph, then grep for string-keyed and dynamic readers, then Read spans. If the graph is missing and the question spans 3+ subsystems, build it once (interlock-graph build .). Never rebuild when it already exists.

When to fan out

Fan out when the question shows any of these:

Mandatory fan-out — shared or derived value changes. If the change alters what a value means or who reads it, run Pattern 4 per ${CLAUDE_PLUGIN_ROOT}/shared/INVARIANT-SWEEP.md. This overrides the single-threaded default.

Stay single-threaded for conversational back-and-forth, single-file questions, quick clarifications, sequential discovery where A informs B, or when the user is thinking out loud.

When genuinely unsure, start single-threaded and escalate once you realize the question is broader than it looked.

The four patterns

Pattern 1 — Subsystem mapping. The question spans several parts of the system. One investigator per stage of the flow. Synthesize into a diagram plus narrative.

Pattern 2 — Option comparison. Several viable approaches. One investigator per option, each reporting fit against this codebase, not generic pros and cons. Synthesize into a comparison table plus a recommendation.

Pattern 3 — Layer sweep. "Where does X happen?" when X could happen at several layers. One investigator per layer (client, API, business logic, persistence, post-processing). Synthesize into what each layer catches and where the gaps are.

Pattern 4 — Impact analysis. A change would alter what a value means or who reads it. One investigator per disjoint layer of the blast radius. Synthesize into an impact map with severity per area, and explicitly flag readers still consuming the raw, untransformed form.

Investigator rules

1. Focused prompts. Not "explore everything about X" — "trace the exact flow of Y through files A, B, C".
2. Read-only. Investigators search, read, and report. They never write.
3. Structured returns. JSON only (schema below). No narrative dump.
4. 2–5 agents. Fewer than 2 is not a fan-out; more than 5 means the decomposition is too granular.
5. Disjoint scopes. Non-overlapping assignments so findings merge cleanly. For Pattern 4 this is load-bearing: partition the search space so no reader is missed or double-counted.
6. Label clearly so progress is visible.
7. Use `subagent_type: "Explore"` for read-only investigation.
8. Context hygiene. Wrap user-supplied values per ${CLAUDE_PLUGIN_ROOT}/shared/CONTEXT-HYGIENE.md before echoing them into a subagent prompt.
9. Locate before Read — graph, then grep, then Read spans.
10. Route every investigator. Before the first spawn, run interlock routing explore-investigator --json once, not once per investigator. Pass its model and effort on every investigator call; a null means omit that parameter, and the host's default applies. Print every line of its banners verbatim before the fan-out. When the command exits non-zero, print ROUTING UNAVAILABLE: <first line of its output> and spawn at the session defaults — routing is a cost hint, never a reason to stop. Name no model and no effort level anywhere in this skill or in a prompt it emits; the CLI publishes them.

Prompt template

Investigate: [[SPECIFIC_QUESTION]]
 
Context: [[BROADER_TOPIC]]
 
Look for:
- [specific thing 1]
- [specific thing 2]
 
Return JSON only:
{ "files": [{ "path": "", "lines": "" }], "how": "", "connections": [], "gaps": [] }

Resolve [[SPECIFIC_QUESTION]] and [[BROADER_TOPIC]] from session state at emit time. An unresolved placeholder halts the fan-out — never gap-fill one.

Synthesis

After investigators return, you must synthesize. Never dump raw agent output.

1. Merge overlapping findings — agents often reach the same file from different angles.
2. Build one unified picture — a diagram where structure matters.
3. Name the gaps — what did no agent find? What is still unclear?
4. Surface contradictions — when two agents disagree, say so; do not silently pick one.
5. Run a completeness check. Before closing, ask what is missing: a layer not swept, a reader not checked, an option not costed. For Pattern 4 this is mandatory — if any layer of the blast radius went uncovered, say so outright. A silent gap reads as "we covered everything" when you didn't.
6. Offer direction. What is worth exploring next? In autonomous mode, pursue it or record it in the brief rather than asking.

The result should read like a senior engineer who just debriefed four specialists — not like four reports stapled together.

OpenSpec awareness

openspec list --json          # is there an active change?

When a change exists, read its artifacts via openspec status --change "<name>" --json for context, and offer to capture decisions as they crystallize:

Every ambiguity becomes a ledger row

Follow ${CLAUDE_PLUGIN_ROOT}/shared/DECISION-LEDGER.md. Do not restate its format.

• ## Pending Clarifications → needs_human rows.
• ## Assumptions Made → agent_resolved rows with followable evidence (obvious is not evidence).
• Never only chat — a conversational answer still gets a row citing the human.

Active change → write openspec/changes/<change>/decisions.md now and run interlock ledger <change>. No change yet → number them D1, D2, … in the brief (class stated) so /interlock:spec transcribes them. Never renumber; never reuse an id.

Exit

Conversational mode ends when the user has what they need.

Autonomous mode ends by writing the explore brief and reporting its path — the brief is what /interlock:spec reads instead of re-deriving discovery. Writing it is how explore pays forward.