smith-explore

name	smith-explore
description	Pre-change exploration — audits codebase for system-wide impacts, identifies touch points, and surfaces conflicts before proceeding with smith-new or other workflows.
argument-hint	[<feature-description>] [--scope skills|hooks|configs|all] [--deep]

Smith Explore — Pre-Change Impact Analysis

A diagnostic workflow that audits the codebase for system-wide impacts BEFORE making changes. Identifies all touch points, surfaces conflicts and redundancies, and produces a structured exploration report. Use as the first phase of smith-new or manually before significant changes.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Append entries using this format:

### [HH:MM:SS] /smith-explore <event>

**User Request:**
> <verbatim user message or feature description that triggered this exploration>

**Synthesized Input:** <brief summary of what's being explored>
**Outcome:** <what was discovered>
**Artifacts:** <files read, patterns found>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — capture the verbatim exploration request AND the scope
2. After each sub-agent completes — findings summary
3. After conflict detection — conflicts found with severity
4. On completion — total touch points, conflicts requiring resolution

When to Use This

Use /smith-explore when:

• Starting a new feature that may have cross-system impacts
• Making changes to core infrastructure (skills, hooks, config files)
• Uncertain about the blast radius of a proposed change
• Want to understand existing patterns before adding new ones

This skill is automatically invoked as Phase 0 of /smith-new when --explore is passed or when the feature touches core Smith infrastructure.

Phase 1: Scope Detection

Phase 1 now uses the manifest as a map, not a fence — start narrow, expand as needed.

Pre-2026-05: Phase 1 used blind grep/find across the entire codebase. Post-manifest-system: we start with the precomputed manifest (via /smith-navigate) for the common case, falling back to whole-codebase grep when the manifest doesn't cover the query.

Step 1: Manifest-Driven Candidate Lookup

First, invoke /smith-navigate with the user's feature description (or the verbatim exploration target from $ARGUMENTS). This returns a categorized file list from the project manifest:

/smith-navigate "<feature description from $ARGUMENTS>"

Capture the navigator's output — the Must Read, Should Read, Reference Only, and Systems Affected sections become the initial set of candidate locations to investigate.

If .smith/index/manifest.md is missing (project hasn't been indexed), /smith-navigate will emit a "Manifest not initialized" sentinel. In that case, skip directly to Step 3 (whole-codebase grep) with this one-line note appended to the exploration report:

"Manifest not initialized — using whole-codebase grep. Run /smith-index to enable faster scoped exploration."

Step 2: Focused Grep on Navigator Output

Grep the locations returned by /smith-navigate plus their immediate neighborhoods (parent directories, sibling files in the same module). This is the focused pass and covers the common case where the manifest already knows where the relevant code lives.

For each candidate path:

• Read the file (or its primary section per the [primary: <range>, <label>] annotation)
• Grep its parent directory for related symbols
• Note any imports/exports that point to other manifest entries

Step 3: Whole-Codebase Expansion (if needed)

Escalate to a whole-codebase grep when ANY of these conditions hold:

• /smith-navigate returned no candidates (manifest doesn't cover the query)
• Initial focused grep finds signals of broader impact (e.g., a function used across many files, a global constant, a shared utility)
• The query mentions concepts not present in any system manifest
• The user explicitly passed --deep

When escalating, use the legacy --scope matrix below to bound the search:

Scope Matrix (used by Step 3 and explicit --scope flags)

Flag	Scope	What to scan
--scope skills	Smith skills only	~/.claude/skills/smith-*/**/*.md
--scope hooks	Hooks and plugins	~/.claude/plugins/**/*, settings.json hooks
--scope configs	Config files only	constitution.md, CLAUDE.md, MEMORY.md
--scope all	Everything	All of the above
(no flag)	Auto-detect	Infer from feature description

Auto-detection rules:

• If description mentions "skill", "workflow", "smith" → scan skills
• If description mentions "hook", "automation", "trigger" → scan hooks
• If description mentions "config", "constitution", "memory", "claude.md" → scan configs
• If description mentions "policy", "rule", "standard" → scan constitution.md
• If unclear → scan all

Phase 2: Parallel Sub-Agent Investigation

Launch diagnostic sub-agents based on scope. Each sub-agent is read-only.

2.1 Skills Pattern Agent

Model: haiku Task: Scan all Smith skills for patterns related to the exploration target.

- Find all skills that write to the target files/systems
- Identify shared patterns (vault logging, workflow phases, etc.)
- Note any skills that might conflict with the proposed change
- Report: skills affected, patterns found, potential conflicts

2.2 Configuration Files Agent

Model: haiku Task: Check configuration files for redundancies and conflicts per File Purpose Policy.

- Read constitution.md, CLAUDE.md, MEMORY.md
- Check for existing content that overlaps with proposed change
- Identify redundancies that violate the File Purpose Policy (constitution.md §VI)
- Check for spec drift between files
- Report: redundancies, misplaced content, conflicts with policy

2.3 Hooks & Automation Agent

Model: haiku Task: Identify hooks that might be triggered by or conflict with the change.

- Scan ~/.claude/settings.json for relevant hooks
- Check ~/.claude/plugins/ for automation that touches target systems
- Identify any pre/post tool use hooks that might interfere
- Report: hooks affected, automation conflicts, triggering conditions

2.4 Cross-Reference Agent

Model: sonnet Task: Deep analysis of how proposed change interacts with existing systems.

- Map the proposed change to affected systems via .specify/systems/*/spec.md
- Check for existing features that overlap or conflict
- Identify architectural implications
- Search for prior debug reports or decisions related to this area
- Report: systems affected, architectural concerns, prior art

Sub-Agent Selection

Not all agents are always needed:

Exploration type	Agents to launch
New skill	2.1 (skills) + 2.3 (hooks)
Config file change	2.2 (config) + 2.4 (cross-ref)
Policy change	2.1 (skills) + 2.2 (config) + 2.4 (cross-ref)
New feature	2.4 (cross-ref) only
Full audit	All 4

If --deep flag is passed, always launch all 4 agents.

Phase 3: Conflict Detection & Synthesis

After sub-agents return, synthesize findings into a conflict analysis:

1. Categorize findings by severity:

   • BLOCKING: Must be resolved before proceeding (e.g., policy violation, breaking change)
   • WARNING: Should be addressed but can proceed (e.g., redundancy, minor inconsistency)
   • INFO: Useful context, no action required (e.g., related features, prior decisions)

2. Check against File Purpose Policy (constitution.md §VI):

   • Is the proposed change writing to the correct file?
   • Would it create redundancy with existing content?
   • Does it conflict with the mutually exclusive file purposes?

3. Apply smith-debug cognitive guards:

   • Actively seek evidence that contradicts the initial plan
   • Match recommendations to actual findings, not assumed severity
   • Consider cheapest resolution first

Phase 4: Exploration Report

Write the report to .smith/vault/explore/explore-YYYY-MM-DD-<slug>.md:

---
explored: YYYY-MM-DD
status: clear | conflicts-found | blocking-issues
scope: skills | hooks | configs | all
feature: <proposed feature or change>
---

# Exploration: <short description>

## Proposed Change
<Description of what's being explored/proposed>

## Scope
<What was scanned and why>

## Findings

### Skills Patterns
<Agent 2.1 findings — affected skills, shared patterns, conflicts>

### Configuration Files
<Agent 2.2 findings — redundancies, policy violations, misplaced content>

### Hooks & Automation
<Agent 2.3 findings — affected hooks, automation conflicts>

### Cross-System Analysis
<Agent 2.4 findings — systems affected, architectural concerns>

## Conflicts

### BLOCKING
- [ ] <conflict description> — **Resolution required before proceeding**

### WARNING
- [ ] <issue description> — **Recommended to address**

### INFO
- <context or related information>

## Recommendations

<Suggested approach based on findings>

## Proceed?

Based on this exploration:
- [ ] **Clear to proceed** — no blocking issues
- [ ] **Proceed with caution** — warnings to address
- [ ] **Do not proceed** — blocking issues require resolution first

Phase 5: Decision Gate

Present the exploration summary to the user:

## Exploration Complete

**Proposed:** <one-sentence summary>
**Status:** <clear | warnings | blocking>
**Report saved:** .smith/vault/explore/explore-YYYY-MM-DD-<slug>.md

### Findings Summary
- Skills affected: N
- Config conflicts: N
- Hooks impacted: N
- Systems touched: N

### Issues Found
- BLOCKING: N (must resolve)
- WARNING: N (should address)
- INFO: N (context only)

Would you like to:
[1] Proceed — continue to smith-new with this context
[2] Resolve conflicts — address blocking/warning issues first
[3] Explore deeper — run additional analysis on specific areas
[4] Abort — stop and review findings manually

If invoked from smith-new:

• If status is clear: return findings and continue workflow
• If status is conflicts-found (warnings only): present summary, ask to proceed or resolve
• If status is blocking-issues: STOP, present issues, require resolution before continuing

If invoked standalone:

• Always present decision gate
• Allow user to choose next action

Key Rules

• Read-only: This workflow NEVER modifies code, configs, or skills
• Policy-aware: Always check findings against constitution.md §VI (File Purpose Policy)
• Parallel investigation: Launch sub-agents concurrently to minimize wall-clock time
• Cognitive guards: Fight confirmation bias — actively look for reasons NOT to proceed
• Preserve context: Log all findings for later reference, even if user proceeds
• Smith-debug framing: Present conflicts clearly with severity, not just a pass/fail