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-discover is the bridge between an existing codebase and the SDD workflow. It analyzes your source directories, infers the architectural domains your project is organized around, and generates a canonical spec for each one. These specs serve as a starting-point record of what your code currently does — ready for you to review, correct, and build on with future changes.

​
Usage

/sdd-discover            # Analyze the entire project
/sdd-discover {domain}   # Analyze a specific domain only

​
Prerequisites

  • /sdd-init has been run — openspec/ exists with a valid config.yaml
  • Project skills are loaded

​
What it does

1
Step 1 — Detect domains
2
Explores common source roots to infer the architectural domains in the project:
3
# Scan common source roots
ls src/ app/ lib/ packages/ 2>/dev/null

# Locate top-level directories
find src app lib packages -maxdepth 1 -type d 2>/dev/null

# Find source files
find . -maxdepth 2 -name "*.py" -o -name "*.ts" -o -name "*.php" \
       -o -name "*.rb" -o -name "*.go" -o -name "*.rs" 2>/dev/null | head -50
4
Domain inference follows these rules:
5
Directory foundInferred domainsrc/{name}/ or app/{name}/{name}tests/, spec/, __tests__/, test/tests.py/.ts/.php files at project root{project name} or root
6
The following directories and files are always ignored: node_modules/, vendor/, .git/, dist/, build/, __pycache__/, .venv/, coverage/, openspec/, .claude/, .cursor/, .github/copilot-instructions.md.
7
If a {domain} argument is provided, auto-detection is skipped and only that domain is analyzed.
8
Step 2 — Interactive summary
9
Before any files are written, shows the detected domains and asks for confirmation:
10
Detected domains:
  - core      (src/core/  — 12 .py files)
  - tui       (src/tui/   — 9 .py files)
  - tests     (tests/     — 28 .py files)

Proceed with analysis? [Y/n]
11
Domains that already have a spec are flagged and skipped:
12
  - core      → spec already exists, will be skipped
13
If the user answers N, the command stops without creating any files.
14
Step 3 — Per-domain analysis (parallel subagents)
15
After confirmation, launches one subagent per domain in parallel. Each subagent:
16
  • Explores the domain files using Glob and Read, prioritizing entry points, models, and public interfaces
  • Infers the domain’s purpose, key entities, and main behavior
  • Generates openspec/specs/{domain}/spec.md following the canonical spec format
  • Returns a one-line confirmation to the orchestrator
    • 17
    The prompt prefix is kept identical across all subagents so that parallel runs benefit from prompt-cache hits. Only the domain name and path differ between agents.
    18
    Each generated spec follows this structure:
    19
    # Spec: {Domain} — {Descriptive Title}

## Metadata
- **Domain:** {domain}
- **Change:** sdd-discover
- **Date:** {current date}
- **Version:** 1.0
- **Status:** inferred

## Context
{2-4 lines: what problem this domain solves in the system}

## Current Behavior
{Description of what the code implements today}

## Requirements (EARS)
- **REQ-01** `[Ubiquitous]` The {actor} SHALL {invariant}
- **REQ-02** `[Event]` When {trigger}, the {actor} SHALL {response}

## Decisions Made
| Decision | Discarded Alternative | Reason |
|----------|-----------------------|--------|

## Open / Pending
- [ ] {Aspects unclear during analysis}
    20
    Step 4 — Update openspec/INDEX.md
    21
    After all subagents report back, updates the domain index:
    22
  • If openspec/INDEX.md exists — adds entries for newly generated domains without modifying existing ones
  • If openspec/INDEX.md does not exist — creates it with a standard header and one entry per domain
    • 23
    Each entry follows this format:
    24
    ## {domain} (`specs/{domain}/spec.md`)
{1-2 line description of the domain}
**Entities:** {main entities}
**Keywords:** {relevant keywords}
    25
    Step 5 — Final summary
    26
    sdd-discover complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Specs generated (Status: inferred):
  ✓ core    → openspec/specs/core/spec.md
  ✓ tui     → openspec/specs/tui/spec.md
  ✓ tests   → openspec/specs/tests/spec.md
Skipped: —

Next steps:
  Review each spec directly in openspec/specs/{domain}/spec.md
  Edit inferred specs to correct any inaccuracies
  When a domain needs changes later, /sdd-new will create a delta spec via /sdd-spec

    ​
    Output

    ArtifactPath
    Canonical spec per domainopenspec/specs/{domain}/spec.md
    Domain indexopenspec/INDEX.md
    All specs are written with Status: inferred. Source code is never modified — /sdd-discover is read-only on your project files and only writes into openspec/.

    ​
    Skill metadata

    FieldValue
    namesdd-discover
    model_hintsonnet
    requiresopenspec/config.yaml
    producesopenspec/specs/*/spec.md, openspec/INDEX.md

    ​
    Idempotent by design

    Domains that already have a spec.md are always skipped — no overwriting, no errors. You can safely run /sdd-discover {domain} on a single domain without affecting others.
    All specs generated by /sdd-discover carry Status: inferred — an explicit signal that they are automatic drafts, not human-validated specs. Review them, correct inaccuracies, and fill in the open questions before relying on them for future changes.

    ​
    Next steps

    • Review each spec in openspec/specs/{domain}/spec.md and edit to correct any inaccuracies or fill in open questions
    • /sdd-steer sync — if conventions in steering/ may have drifted, check for updates before starting new work
    • /sdd-new "description" — start your first change; delta specs created via /sdd-spec will sit alongside these canonical specs

    Build docs developers (and LLMs) love

    Get started for freeTalk to us