Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

/sdd-explore is a read-only skill that builds context before any change is proposed. It searches project history for past decisions in the same domain, then scans the live codebase for patterns, affected files, and existing specs. The result is a structured notes.md that downstream skills — especially /sdd-propose — use to fill in impact, scope, and dependencies. You will rarely need to invoke it directly: it runs automatically inside /sdd-new. Use it standalone when you want to understand a part of the codebase before deciding what to change.

​
Usage

/sdd-explore "how does authentication work"   # Explore a specific topic
/sdd-explore                                  # General exploration for the active change

​
Prerequisites

  • openspec/config.yaml must be present
  • No other artifacts are required — this skill can run at any time

​
What it does

1

Recall past decisions

Before reading any current code, searches project history for relevant context. Scans:
  • openspec/INDEX.md — the domain index
  • openspec/specs/ — canonical specs by domain
  • openspec/changes/archive/ — completed changes and their decisions
Looks for previous specs in the same domain, design decisions that explain why something was built a certain way, and proposals that addressed a similar problem (including discarded alternatives). If no archive or specs exist yet (new project), this step is skipped silently.
2

Identify relevant domains via OpenSpec Index

If openspec/INDEX.md exists, reads it first and matches the change description or topic keywords against each entry’s **Keywords:** field. Loads only the 1–3 most relevant domain spec files rather than everything in openspec/specs/. If INDEX.md does not exist, scans openspec/specs/ directly as a fallback.
3

Scan the codebase

Reads current code to identify:
  • Similar patterns — existing implementations of the same type of change
  • Affected files — what will need to change and why
  • Domain models — data structures, interfaces, contracts involved
  • Test structure — how existing tests are organized for similar code
4

Write notes.md and show summary

Persists findings to openspec/changes/{change-name}/notes.md so they survive across sessions and can be read by /sdd-propose. Also prints a terse summary to the conversation — bullet lists, no prose.

​
Output

/sdd-explore creates one file and never modifies code: openspec/changes/{change-name}/notes.md 
# Exploration Notes: {change-name}

## Prior Decisions
- {domain}: {decision from archived spec/design — why it matters for this change}
- {domain}: {discarded alternative — avoid repeating}

## Relevant Files
- `src/...` — {reason}
- `src/...` — {reason}

## Existing Patterns
- Pattern X used in Y — can follow the same approach

## Relevant Specs
- `openspec/specs/{domain}/spec.md` — {why relevant}

## Key Constraints
- {anything that affects the design}
The conversation summary follows a fixed format: 
EXPLORE COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Notes written to: openspec/changes/{change-name}/notes.md

Prior decisions:
  - {domain}: {key decision or discarded alternative}

Relevant files:
  - src/...   (reason)

Existing patterns:
  - Pattern X used in Y — can follow the same approach

OpenSpec Index (if present):
  - openspec/INDEX.md → identified domains: {domain1}, {domain2}
  - Loaded specs: openspec/specs/{domain}/spec.md

Key constraints:
  - {anything that affects the design}
This is the recall step of the SDD workflow. Checking archived specs and past decisions before reading current code is what prevents repeating discarded approaches and reinventing patterns that already exist.

​
Skill metadata

PropertyValue
model_hintsonnet
requiresopenspec/config.yaml
producesopenspec/changes/{change}/notes.md

​
Next steps

After exploration, run /sdd-propose to draft the change proposal — it will automatically read notes.md to inform the Impact, Scope, and Dependencies sections. If you ran /sdd-explore as part of /sdd-new, the propose phase starts immediately after.

Build docs developers (and LLMs) love

Get started for freeTalk to us