Sdd Explore

<!-- MEMORY-CONTRACT v1 -->

Memory contract. This command persists across sessions through engram

(registered as an MCP server in this tool). Use this tool's own engram memory

tools to honor the rules below — do not assume any other persistence layer.

>

- Recall before acting: on a continuation keyword ("listo", "dale",

"ready", "where did we leave off"), first search engram for prior work on

this change before starting fresh; summarize what you found, then continue.

- Validate after saving: after any save, search engram back for the key or

a unique phrase — a "saved" tool response is NOT proof. Retry once; if it

still fails, tell the user the save failed. Never report "saved" on the tool

response alone.

- Summarize at close: before ending, write a session summary (goal, work

done, decisions, next steps, files). Recovery is never automatic.

- If engram is unreachable (not installed / not on PATH): emit a visible

warning that engram was not found and that this work will NOT persist. DO NOT

report memory as saved; DO NOT proceed silently as if it had persisted.

Purpose

EXPLORE is a mandatory gate of any SDD cycle that proceeds past it. It runs before propose, spec, design, tasks, and apply, and produces a persisted, citation-bearing artifact. No downstream phase may begin until EXPLORE has written its artifact to disk. It creates no code and modifies nothing — it only reads and analyzes.

Process

Step 0 — Load project context + Spec context preload

Load the project's context (conventions, architecture notes) and the change's spec scenarios if present. Both are non-blocking.

EXPLORE-local override (deliberate): EXPLORE MUST attempt to read ai-context/features/<domain>.md AND ai-context/architecture.md. If either file is absent, emit an explicit INFO: note (e.g., INFO: ai-context/features/<domain>.md not found — proceeding without domain context) and continue. The run MUST NOT be blocked or marked status: blocked due to absence. Silent skipping is not permitted here — absence is a visible, non-blocking signal.

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. Search prior work for an existing proposal under the key sdd/<slug>/proposal. 3. If absent: skip silently — log INFO: no pre-seeded proposal found — proceeding without handoff context. 4. If present: retrieve it. 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: 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

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 prior work for archived changes related to this topic (archive reports for the project).

Filter results by keyword overlap with the current change slug. For each related result, retrieve it 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

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/features/<domain>.md and ai-context/architecture.md — EXPLORE MUST attempt to read both. If absent, emit INFO: <path> not found — proceeding without domain context and continue. Each claim gathered here MUST be recorded with its path:line evidence for inclusion in ## Key Findings (cited).

Step 6 — Analyze approaches

For each possible approach generate a comparison table:

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>, persist the exploration artifact.

Write (disk-primary): first write the full exploration markdown to docs/sdd/{change-name}/explore.md (the source of truth), then persist a pointer + summary keyed sdd/{change-name}/explore for prior-work recall.

• If no change name provided: log INFO: no change name — skipping artifact persistence and skip.
• If the prior-work store is not reachable: still write the disk artifact (the source of truth); skip the pointer only.

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

# Exploration: [topic]

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

## Key Findings (cited)

- [domain rule or structural claim] — path/to/file.ext:LINE
- [claim spanning a range] — path/to/file.ext:START-END
- [absence claim] — verified by: <reproducible check> → <result>
  (e.g. "no citation requirement exists — verified by: grep -r 'citation' skills/sdd-explore/ → 0 matches")

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

## Prior Attempts
- [slug]: [outcome]
[or: "None found."]

## Contradiction Analysis
- [Item]: [CERTAIN|UNCERTAIN] — [one-line explanation]
[or: "No contradictions detected."]

## Recommendation
[Recommended approach in 1-2 sentences]

## Ready for Proposal
[Yes/No — and why if No]

Every entry in ## Key Findings (cited) MUST carry path:line evidence (or, for an absence claim, a reproducible check + its result); an uncited claim is an invalid exploration.

Conversational output (shown to user but NOT persisted):

The full analysis — including Affected Areas table, Analyzed Approaches with pros/cons/effort/risk, Identified Risks with mitigations, Open Questions, and Handoff Context — is presented in the conversational response to the orchestrator. This content is ephemeral and does not need to survive across sessions.

Output Contract

Return this result shape:

{
  "status": "ok|warning|blocked",
  "summary": "Analysis of [topic]: [2-3 lines of the main finding]",
  "artifacts": ["docs/sdd/{change-name}/explore.md"],
  "next_recommended": ["sdd-propose"],
  "risks": ["[risk if found]"]
}

Rules

• ONLY read code — never modify anything in this phase
• Read real code, never assume or invent
• If something unexpected is found (technical debt, inconsistencies), report it
• Keep the analysis concise: the goal is to inform, not to write a thesis
• If the exploration reveals that the change is trivial, say so clearly
• Every domain rule and every structural claim in ## Key Findings (cited) MUST quote path:line evidence (or, for an absence claim, a reproducible check + its result). A claim without a citation is an invalid exploration.