sdd-explore

What this skill does

# sdd-explore

> Investigates and analyzes an idea or area of the codebase before committing to changes.

**Triggers**: `/sdd-explore <topic>`, explore, investigate codebase, analyze before changing, research feature

---

## Purpose

The exploration phase is **optional but valuable**. Its goal is to understand the terrain before proposing changes. It creates no code and modifies nothing. It only reads and analyzes.

Use it when:

- The request is vague or complex
- You are unsure of the scope of the change
- You want to understand the impact before committing
- There are multiple possible approaches

---

## Process

### Skill Resolution

When the orchestrator launches this sub-agent, it resolves the skill path using:

```
1. .claude/skills/sdd-explore/SKILL.md     (project-local — highest priority)
2. ~/.claude/skills/sdd-explore/SKILL.md   (global catalog — fallback)
```

Project-local skills override the global catalog. See `docs/SKILL-RESOLUTION.md` for the full algorithm.

---

### Step 0 — Load project context + Spec context preload

Follow `skills/_shared/sdd-phase-common.md` **Section F** (Project Context Load) and **Section G** (Spec Context Preload). Both are non-blocking.

### Step 0 sub-step — Handoff context preload

This sub-step is **non-blocking**: any failure (missing file, unreadable file, no slug) MUST produce
at most an INFO-level note. This sub-step MUST NOT produce `status: blocked` or `status: failed`.

1. Resolve the change slug from the invocation context.
2. Check whether a proposal already exists in engram: `mem_search(query: "sdd/<slug>/proposal")`.
3. If absent: skip silently — log `INFO: no pre-seeded proposal found — proceeding without handoff context.`
4. If present: retrieve via `mem_get_observation(id)`. Treat its content as **supplemental intent enrichment**:
   - It informs what the explore should prioritize, not what the codebase shows.
   - It MUST NOT override live codebase findings.
   - Log: `Handoff context loaded from engram: sdd/<slug>/proposal`
5. When loaded, include a `## Handoff Context` section in the exploration output
   (placed before `## Current State`) summarizing:
   - Decision that triggered the change
   - Goal and success criteria from the seeded proposal
   - Explore targets listed in the proposal
   - Constraints ("do not do" items)

---

### Step 1 — Understand the request

I classify what type of exploration is needed:

- **New feature**: What already exists? Where would it fit?
- **Bug**: Where is the problem? What is the root cause?
- **Refactor**: What code is affected? What are the risks?
- **Integration**: What exists to connect? What is missing?

### Step 2 — Branch Diff scan

This step is **non-blocking**: any failure (git unavailable, no working tree, empty diff) MUST produce at most an INFO-level note. This step MUST NOT produce `status: blocked` or `status: failed`.

1. Run `git status --short` to identify modified, staged, and untracked files in the current working tree.
2. Filter results to files relevant to the domain being explored (match by path prefix, filename, or keyword overlap with the change name).
3. Classify each file as: `modified`, `staged`, `deleted`, or `untracked`.
4. Write output to the `## Branch Diff` section.

**If git is unavailable or diff is empty**: log `INFO: branch diff unavailable or empty — skipping Branch Diff section` and include an empty `## Branch Diff` section with that note.

**Output format:**
```
## Branch Diff

Files modified in current branch relevant to this change:
- path/to/file.ts (modified)
- path/to/other.ts (staged, pending deletion)
- path/to/new-file.ts (untracked)
```

### Step 3 — Prior Attempts archive scan

This step is **non-blocking**: any failure MUST produce at most an INFO-level note.

Search engram for prior archived changes related to this topic:
```
mem_search(query: "sdd/archive-report", project: "{project}")
```

Filter results by keyword overlap with the current change slug. For each related result, retrieve via `mem_get_observation(id)` to check outcome.

Write output to the `## Prior Attempts` section.

**Output format:**
```
## Prior Attempts

Prior archived changes related to this topic:
- auth-flow-v1: COMPLETED
- auth-flow-v2: ABANDONED

[or: "No prior attempts found."]
```

### Step 4 — Contradiction Analysis

This step is **non-blocking**: contradictions are informational and MUST NOT cause `status: blocked` or `status: failed`. At most, contradictions may cause `status: warning`.

1. Compare the user's stated intent (from change description and any pre-seeded proposal) against:
   - Loaded feature files from Step 0 (behavioral contracts)
   - Prior attempt outcomes from Step 3
   - `ai-context/` files
2. For each potential contradiction detected, classify severity:
   - **CERTAIN**: the user says "remove X" AND a loaded spec explicitly states "X MUST exist" — no ambiguity
   - **UNCERTAIN**: the user intent implies removing or changing X, but there is no explicit spec contract — ambiguous
3. Assign impact level: `INFO` (minimal), `WARNING` (notable), `CRITICAL` (breaking)
4. Write output to the `## Contradiction Analysis` section.
5. Do NOT block exploration — the status remains `ok` unless contradictions are severe enough to set `status: warning`.

**Output format:**
```
## Contradiction Analysis

Contradictions detected between user intent and existing context:

- Item: [feature or behavior name]
  Status: CERTAIN|UNCERTAIN — [explanation of what contradicts what]
  Severity: INFO|WARNING|CRITICAL
  Resolution: [suggested resolution or "Requires user confirmation"]

[or: "No contradictions detected."]
```

### Step 5 — Investigate the codebase

I read real code following this hierarchy:

1. Entry points of the affected area
2. Files related to the functionality
3. Existing tests (they reveal expected behavior)
4. Relevant configurations
5. `ai-context/architecture.md` if it exists (to understand past decisions)

### Step 6 — Analyze approaches

For each possible approach I generate a comparison table:

| Approach   | Pros | Cons | Effort          | Risk            |
| ---------- | ---- | ---- | --------------- | --------------- |
| [Option A] |      |      | Low/Medium/High | Low/Medium/High |
| [Option B] |      |      |                 |                 |

### Step 7 — Identify risks and dependencies

- Code that would break with the change
- Dependencies that would need to be updated
- Tests that would fail
- Non-obvious side effects

### Step 8 — Save if a change name was specified

**Pre-save naming check (non-blocking):**

If `<change-name>` starts with `explore-`, warn before writing:

```
Note: The change name "[change-name]" starts with "explore-".
Standalone explore folders (e.g. explore-fy-topic) are not part of a full SDD planning cycle
and will not be automatically cleaned up or archived.

If you intend this as a full SDD change, use a descriptive slug and continue with /sdd-propose:
  /sdd-propose <description>   <- starts the planning cycle from proposal

If you intend this as a one-off investigation, proceed as-is.
```

This warning is informational only — writing proceeds regardless of the name.

If invoked as `/sdd-explore <change-name>`, I persist the exploration artifact.

**Write:** Call `mem_save` with `topic_key: sdd/{change-name}/explore`, `type: architecture`, `project: {project}`, content = full exploration markdown. Do NOT write any file.
  - If no change name provided: log `INFO: no change name — skipping artifact persistence` and skip.
  - If Engram MCP is not reachable: skip persistence. Return exploration content inline only.

**Persisted artifact** (compact — only what downstream phases consume):

```markdown
# Exploration: [topic]

## Current State
[2-3 sentence summary of what currently exists in the codebase]

## Branch Diff
- [path/to/file] (modified|staged|deleted|untracked)
[or: "No relevant changes in current branch."]

## Prior Attempts
- [slug]: [outcome]
[or: "