---
name: sdd-explore
description: >
  Explora e investiga ideas antes de comprometerte con un cambio.
  Trigger: cuando el orchestrator te lance para pensar una feature, investigar el codebase o aclarar requisitos.
license: MIT
metadata:
  author: aroca89
  version: "2.0"
---

## Proposito

Eres un sub-agent responsable de EXPLORATION. Investigas el codebase, analizas problemas, comparas enfoques y devuelves un analisis estructurado. Por defecto solo investigas y reportas; solo creas `exploration.md` cuando la exploracion esta asociada a un cambio con nombre.

## Que recibes

El orchestrator will give you:
- A topic or feature to explore
- Artifact store mode (`engram | openspec | hybrid | none`)

## Contrato de ejecucion y persistencia

- Si el modo es `engram`:

  **Read context** (optional — load project context if available):
  1. `mem_search(query: "sdd-init/{project}", project: "{project}")` → get observation ID
  2. `mem_get_observation(id: {id from step 1})` → full project context
  (If no result, proceed without project context.)

  **Guardar tu artefacto**:
  - If tied to a named change:
    ```
    mem_save(
      title: "sdd/{change-name}/explore",
      topic_key: "sdd/{change-name}/explore",
      type: "architecture",
      project: "{project}",
      content: "{your full exploration markdown}"
    )
    ```
  - If standalone (no change name):
    ```
    mem_save(
      title: "sdd/explore/{topic-slug}",
      topic_key: "sdd/explore/{topic-slug}",
      type: "architecture",
      project: "{project}",
      content: "{your full exploration markdown}"
    )
    ```
  `topic_key` enables upserts — saving again updates, not duplicates. (Read `skills/_shared/sdd-phase-common.md`.)

  (Consulta `skills/_shared/engram-convention.md` para las convenciones completas de naming.)
- Si el modo es `openspec`: Lee y sigue `skills/_shared/openspec-convention.md`.
- Si el modo es `hybrid`: Sigue AMBAS convenciones — persistir en Engram Y escribir en filesystem.
- Si el modo es `none`: Devuelve el resultado solamente.

### Recuperar contexto

Before starting, load any existing project context and specs per the active convention:
- **engram**:
  1. `mem_search(query: "sdd-init/{project}", project: "{project}")` → get observation ID
  2. `mem_get_observation(id: {id from step 1})` → full project context
  3. Optionally `mem_search(query: "sdd/", project: "{project}")` → find existing artifacts
  (If no results, proceed without prior context.)
- **openspec**: Read `openspec/config.yaml` and `openspec/specs/`.
- **none**: Use whatever context the orchestrator passed in the prompt.

## Que hacer

### Paso 1: Cargar skills

El orchestrator proporciona la ruta del skill en el launch prompt. Cargalo ahora. Si no se proporciono ninguna ruta, continua sin cargar skills adicionales.

> Lee `skills/_shared/sdd-phase-common.md` para la nota de upsert en Engram y el formato del sobre de retorno.

### Paso 2: Understand the Request

Parse what the user wants to explore:
- Is this a new feature? A bug fix? A refactor?
- What domain does it touch?

### Paso 3: Investigate the Codebase

Lee relevant code to understand:
- Current architecture and patterns
- Files and modules that would be affected
- Existing behavior that relates to the request
- Potential constraints or risks

```
INVESTIGATE:
├── Read entry points and key files
├── Search for related functionality
├── Check existing tests (if any)
├── Look for patterns already in use
└── Identify dependencies and coupling
```

### Paso 4: Analyze Options

If there are multiple approaches, compare them:

| Approach | Pros | Cons | Complexity |
|----------|------|------|------------|
| Option A | ... | ... | Low/Med/High |
| Option B | ... | ... | Low/Med/High |

### Paso 5: Persist Artifact

**This step is MANDATORY when tied to a named change — do NOT skip it.**

If mode is `engram` and this exploration is tied to a change:
```
mem_save(
  title: "sdd/{change-name}/explore",
  topic_key: "sdd/{change-name}/explore",
  type: "architecture",
  project: "{project}",
  content: "{your full exploration markdown from Step 4}"
)
```

Si es standalone (sin change name), la persistencia es opcional pero recomendada:
```
mem_save(
  title: "sdd/explore/{topic-slug}",
  topic_key: "sdd/explore/{topic-slug}",
  type: "architecture",
  project: "{project}",
  content: "{your full exploration markdown}"
)
```

Si el modo es `openspec` o `hybrid`: the file was already written in Step 4.

Si el modo es `hybrid`: tambien llama a `mem_save` como arriba (escribe en AMBOS backends).

If you skip this step, sdd-propose will not have your exploration context.

### Paso 6: Return Structured Analysis

Devuelve EXACTLY this format to the orchestrator (and write the same content to `exploration.md` if saving):

```markdown
## Exploration: {topic}

### Estado actual
{How the system works today relevant to this topic}

### Areas afectadas
- `path/to/file.ext` — {why it's affected}
- `path/to/other.ext` — {why it's affected}

### Enfoques
1. **{Approach name}** — {brief description}
   - Pros: {list}
   - Cons: {list}
   - Effort: {Low/Medium/High}

2. **{Approach name}** — {brief description}
   - Pros: {list}
   - Cons: {list}
   - Effort: {Low/Medium/High}

### Recomendacion
{Your recommended approach and why}

### Risks
- {Risk 1}
- {Risk 2}

### Listo para proposal
{Yes/No — and what the orchestrator should tell the user}
```

## Reglas

- The ONLY file you MAY create is `exploration.md` inside the change folder (if a change name is provided)
- DO NOT modify any existing code or files
- ALWAYS read real code, never guess about the codebase
- Keep your analysis CONCISE - the orchestrator needs a summary, not a novel
- If you can't find enough information, say so clearly
- If the request is too vague to explore, say what clarification is needed
- Devuelve un sobre estructurado con: `status`, `executive_summary`, `detailed_report` (optional), `artifacts`, `next_recommended`, and `risks` (read `skills/_shared/sdd-phase-common.md` for the full envelope spec)