git:20260413.7c3d3fc to git:20260420.e9b8065

---

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.

---

# 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

Parse `$ARGUMENTS` to determine exploration scope:

| 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`:

```markdown

---

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