Skip to main content

discover

Discover implicit architectural decisions and spec-worthy subsystems in an existing codebase. Use when the user says "discover architecture", "what decisions exist in this code", "bootstrap ADRs", or wants to reverse-engineer design artifacts from code.

Governing Artifacts​

ADR-0016 · ADR-0024 · ADR-0026 · ADR-0033 · SPEC-0014 · SPEC-0019 · SPEC-0034

Usage​

/sdd:discover [scope] [--module <name>] [--with-graphs]
Required Tools
  • Bash
  • Read
  • Glob
  • Grep
  • Task
  • AskUserQuestion

Overview​

Harness portability. This skill runs on any agent harness that loads Agent Skills — Claude Code, Codex CLI, OpenCode, Crush. Tool names used below (AskUserQuestion, Task, TeamCreate, SendMessage, TaskCreate, ToolSearch, mcp__*, $\{CLAUDE_PLUGIN_ROOT\}) denote capabilities, not hard requirements: map each to your harness's equivalent or use the documented fallback per $\{CLAUDE_PLUGIN_ROOT\}/references/harness-compat.md. References to CLAUDE.md mean the project memory file (CLAUDE.md, AGENTS.md, or CRUSH.md) per harness-compat § "Project Memory File". A citation of the form shared-patterns.md § "Section" names one ## heading in that file — load only that section (see its "How to Read This File" note), never the whole file. Invocation and arguments. Where your harness has no command layer (Crush, Codex CLI, OpenCode) this skill is reached from its description, not a slash command: the /sdd:\{name\} form below is Claude Code namespacing. $ARGUMENTS means whatever arrived with the invocation: take the target and any --flags from the request that triggered this skill, and when neither is present follow this skill's documented no-argument path instead of reporting missing arguments (harness-compat § "Invocation and Arguments").

Explore an existing codebase to discover implicit architectural decisions and specification-worthy subsystems. Produces a suggestion report -- does NOT create any files.

Process​

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

  1. Resolve artifact paths: Follow the Artifact Path Resolution pattern from $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Artifact Path Resolution" to determine the ADR and spec directories. If $ARGUMENTS contains --module &lt;name>, resolve paths relative to that module; otherwise, in a workspace, aggregate across all modules. The resolved ADR directory is \{adr-dir\} and spec directory is \{spec-dir\}.

  2. Parse the scope: Extract the optional scope from $ARGUMENTS.

    • A directory path: src/auth/ -- limit analysis to that subtree
    • A domain keyword: auth, api, data -- limit by semantic relevance
    • If $ARGUMENTS is empty, analyze the entire project (or module if --module is set)

  3. Validate the scope (if provided):

    • For directory paths: verify the path exists. If not, report: "Scope not found: \{scope\}. Provide a valid directory path or omit the scope to analyze the entire project."

2a. Tier 3 staleness check (v5.0.0+):

<!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 3 Staleness Threshold for Consumer Skills" -->

On entry, check the qmd index's last-modified timestamp for this repo's collections (use the exact-prefix match algorithm from $\{CLAUDE_PLUGIN_ROOT\}/references/qmd-helpers.md § "This-Repo Collection Identification"). If older than the configured staleness threshold (default 120m, set in CLAUDE.md ### SDD Configuration #### Index Freshness **Staleness Threshold**), trigger a silent qmd update first and emit a one-line note in the report header: Index was \{age\} stale — refreshed before running. On fresh, proceed silently.

  1. Load existing design artifacts:

    • Glob \{adr-dir\}/ADR-*.md and read each file's title, context, and decision outcome
    • Glob \{spec-dir\}/*/spec.md and read each file's title and overview. Validate spec pairing per $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Spec Pairing Validation".
    • Build an exclusion list of already-documented decisions and subsystems
    • If neither directory exists, note that no existing artifacts were found (this is expected for first-time discovery)

  2. Analyze the codebase across four categories. Use the Task tool to spawn parallel Explore agents for each category; each agent should return a list of findings with evidence. On harnesses without subagents, run the four category analyses sequentially inline — same checklists, same findings format — and keep only each category's findings list in context (not the raw file reads) before starting the next category.

    Agent 1 -- Dependency & Framework Analysis:

    • Scan for project manifests (e.g., package.json, requirements.txt, pyproject.toml, Cargo.toml, Gemfile, pom.xml, build.gradle, composer.json, and other ecosystem-specific files).
    • Read dependency lists and identify major framework/library choices
    • Look for lock files to confirm actively used dependencies
    • Identify technology choices that represent architectural decisions (e.g., "chose Next.js over Remix", "chose PostgreSQL over MongoDB", "chose REST over GraphQL")

    Agent 2 -- Architectural Pattern Analysis:

    • Examine code structure for API patterns (REST controllers, GraphQL resolvers, gRPC services)
    • Look for data access patterns (ORM usage, repository pattern, direct queries)
    • Identify authentication/authorization patterns (JWT, sessions, OAuth)
    • Detect state management patterns (Redux, Context, Zustand, etc.)
    • Look for messaging/event patterns (queues, pub/sub, event emitters)
    • Identify error handling and logging patterns

    Agent 3 -- Project Structure & Boundary Analysis:

    • Examine top-level directory layout and module organization
    • Identify subsystem boundaries (directories with cohesive responsibility)
    • Look for monorepo patterns (workspaces, packages/)
    • Identify API surface boundaries (routes, endpoints, public interfaces)
    • Detect data model boundaries (schema files, migration directories, model definitions)
    • Look for clear module interfaces that suggest spec-worthy subsystems

    Agent 4 -- Configuration & Infrastructure Analysis:

    • Scan for Docker/container configuration (Dockerfile, docker-compose.yml, .containerignore)
    • Look for CI/CD configuration (.github/workflows/, .gitlab-ci.yml, Jenkinsfile)
    • Check for infrastructure-as-code (Terraform, CloudFormation, Pulumi)
    • Examine environment configuration (.env.example, config files)
    • Identify deployment targets and hosting decisions
    • Look for monitoring/observability configuration

  3. Merge and deduplicate findings:

    • Combine results from all four agents
    • Group related findings (e.g., "chose Express" and "REST API pattern" both relate to the API layer)
    • Remove findings that overlap with existing ADRs or specs from step 3
    • For partial overlaps, note what the existing artifact covers and what remains undocumented

5a. qmd-aware duplicate suppression (v5.0.0+):

<!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-Smart Drift Skills" -->

Step 5 already removes findings that overlap with existing ADRs/specs from step 3 (which read the corpus directly). v5.0.0 adds a second-pass qmd-based check to catch near-duplicates that the prose-level overlap check missed. For each remaining suggestion:

  1. Construct a qmd query per $\{CLAUDE_PLUGIN_ROOT\}/references/qmd-helpers.md § "Hybrid Retrieval" using the suggestion text:

    • lex: the candidate suggestion's title + key technologies/concepts
    • vec: the candidate suggestion's one-sentence rationale
    • intent: "/sdd:discover — rule out near-duplicates of existing decisions"
    • collections: ["\{repo\}-adrs"] (or per-module variant in workspace mode)
    • limit: 5, minScore: 0.3

  2. If the top result has score >= 0.7 (semantic near-match threshold; configurable via --similarity-threshold flag, defaults to 0.7), suppress the suggestion. The matched ADR likely already covers it — surfacing the suggestion would be noise.

  3. Log every suppressed suggestion in the report's "Skipped (already documented)" section with the matched ADR ID, score, and a one-line note explaining the match. The user can review the suppressions to verify they were correct; if a suppression is wrong, they can re-run with --similarity-threshold 0.85 (or higher) to be more conservative.

On qmd unreachable / timeout per qmd-helpers.md § "Error Handling", surface the error and stop. Per 📝 ADR-0024, the pre-v5 fallback ("just use the prose-overlap check") is gone in v5; the failure mode is "fix qmd, retry."

  1. Assign confidence levels to each suggestion:

    • High: Explicit evidence in declarations or configuration (e.g., dependency in package.json, Dockerfile present)
    • Medium: Inferred from consistent code patterns across multiple files (e.g., repository pattern used in 5+ files)
    • Low: Inferred from limited evidence or indirect signals (e.g., a single config value suggesting a deployment target)

  2. Classify suggestions into two categories:

    • Suggested ADRs: Implicit decisions where an alternative existed (technology choices, pattern choices, architectural trade-offs)
    • Suggested Specs: Subsystem boundaries with enough complexity to warrant formal specification (3+ files, clear interface, distinct responsibility)

7b. Optional call graph enrichment (v5.1.0+, --with-graphs flag):

<!-- Governing: ADR-0033 (cgg call graph integration), SPEC-0034 REQ "cgg Skill Integration With /sdd:discover" -->

This step only runs when $ARGUMENTS contains --with-graphs. Without the flag, skip directly to Step 8 — existing behavior is fully preserved.

For each proposed ADR from Step 7, enrich it with a call graph via /sdd:search:

  1. Extract query keywords: From the ADR suggestion's decision title and evidence (technology names, subsystem names, pattern names), derive 2–4 key search terms. For example, a "Chose JWT for authentication" suggestion yields keywords "JWT authentication".

  2. Determine scope: If discovery is scoped to a specific directory (from Step 1) or --module &lt;name> was passed, derive the --module argument for /sdd:search accordingly so qmd and cgg target only that subtree per $\{CLAUDE_PLUGIN_ROOT\}/references/cgg-integration.md § "Workspace-Mode Scoping".

  3. Invoke /sdd:search: Run /sdd:search "&lt;keywords>" --output json (with --module &lt;name> appended when scoped). Parse the JSON response's call_graphs[] array.

  4. Embed if available: If call_graphs[0].mermaid is non-null, embed the normalized Mermaid diagram in the ADR suggestion's ## Architecture Diagram section in the discovery report, using the embedding format from $\{CLAUDE_PLUGIN_ROOT\}/references/cgg-integration.md § "Embedding in markdown":

    <!-- Call graph: <filter used>, generated <YYYY-MM-DD> -->
    ```mermaid
    graph TD
        ...
    %% Showing entry points + main flow; internal helpers omitted
    ```

  5. Graceful degradation: If /sdd:search is unavailable, errors, or returns call_graphs[0].mermaid: null (cgg degraded), record the failure and continue. After enriching all ADRs, if any call graphs could not be generated, add a single notice line at the top of the discovery report:

    Call graph enrichment unavailable for {N} of {total} suggested ADRs — cgg may not be installed or the codebase is too large. Install cgg with: cargo install cgg

    Never fail discovery because of cgg or /sdd:search unavailability.

  6. Produce the discovery report using the output format below.

Rules​

  • This skill is READ-ONLY -- it MUST NOT create, modify, or delete any files
  • This skill is always single-agent at the top level, but MUST use the Task tool to spawn parallel Explore agents for the four analysis categories when subagents are available; without subagents, MUST run the four analyses sequentially inline, discarding raw file reads between categories
  • Every suggestion MUST cite specific evidence from the codebase -- file paths, dependency declarations, configuration entries, or code patterns
  • Suggestions MUST NOT be based on speculation or assumptions about code that was not read
  • MUST read existing ADRs and specs before producing suggestions to avoid duplicating already-documented decisions
  • MUST include a confidence level (High, Medium, Low) for every suggestion
  • MUST include a ready-to-use /sdd:adr or /sdd:spec command for every suggestion
  • The Command column MUST contain a complete, copy-paste-ready command with a descriptive argument
  • Sort suggestions by confidence (High first, then Medium, then Low) within each section
  • If the scope argument points to a nonexistent path, report the error and stop -- do NOT fall back to full-project analysis
  • Do NOT suggest ADRs for trivial decisions (e.g., "chose npm over yarn" when only one package manager file exists with no evidence of evaluation)
  • Do NOT suggest specs for directories with fewer than 3 files unless they represent a critical subsystem boundary
  • Keep the report concise -- prefer fewer high-quality suggestions over many low-confidence ones
  • Use ## for the top-level heading and ### for sections within the report
  • v5.0.0+: MUST run Tier 3 staleness check on entry per Step 3a — qmd update if older than configured threshold (default 120m) (Governing: 📝 ADR-0026, SPEC-0019 REQ "Tier 3 Staleness Threshold for Consumer Skills")
  • v5.0.0+: MUST run qmd-aware duplicate suppression per Step 5a — for each candidate suggestion, qmd-search \{repo\}-adrs for near-matches; if score ≥ 0.7 (configurable via --similarity-threshold), suppress and log to "Skipped (already documented)" section. The pre-v5 prose-overlap-only check is now first-pass; qmd is the second-pass net (Governing: 📝 ADR-0024, SPEC-0019 REQ "qmd-Smart Drift Skills")
  • v5.0.0+: On qmd unreachable / timeout, MUST surface the error and stop. NEVER fall back to "just use the prose-overlap check" (per 📝 ADR-0024 — fallback paths were eliminated in v5)
  • v5.1.0+ (--with-graphs): When --with-graphs is set, MUST invoke /sdd:search "&lt;keywords>" --output json for each proposed ADR after Step 7 (Step 7b); MUST embed call_graphs[0].mermaid in the ADR's ## Architecture Diagram when non-null; MUST degrade gracefully when /sdd:search or cgg is unavailable — surface a one-line count notice and continue; MUST NOT fail discovery because of cgg unavailability (Governing: 📝 ADR-0033, SPEC-0034 REQ "cgg Skill Integration With /sdd:discover")
  • v5.1.0+ (--with-graphs): Without --with-graphs, Step 7b MUST be skipped entirely — existing /sdd:discover behavior is unchanged (Governing: SPEC-0034 REQ "Must Not Break Existing Workflows")

Output Format​

## Discovery Report

Analyzed {scope or "entire project"}: {N} files across {M} directories.
Found {X} suggested ADRs and {Y} suggested specs.
Existing artifacts: {A} ADRs, {B} specs (excluded from suggestions).

### Suggested ADRs

| # | Confidence | Decision | Evidence | Command |
|---|------------|----------|----------|---------|
| 1 | High | {short decision title} | {key evidence: files, deps, config} | `/sdd:adr {description}` |
| 2 | Medium | {short decision title} | {key evidence} | `/sdd:adr {description}` |

{For each suggestion, add a brief paragraph below the table:}

**1. {Decision title}**
{2-3 sentences explaining what was found, what the implicit decision is, and what alternatives likely existed.}
Evidence: `{file1}`, `{file2}`, `{config entry}`

### Suggested Specs

| # | Confidence | Subsystem | Boundary | Command |
|---|------------|-----------|----------|---------|
| 1 | High | {subsystem name} | {files/dirs that define it} | `/sdd:spec {capability}` |
| 2 | Medium | {subsystem name} | {files/dirs} | `/sdd:spec {capability}` |

{For each suggestion, add a brief paragraph below the table:}

**1. {Subsystem name}**
{2-3 sentences explaining the subsystem's responsibility, its boundaries, and why it warrants a formal spec.}
Boundary: `{dir1}/`, `{dir2}/`, `{key files}`

### Already Documented

{List existing ADRs and specs that cover areas found in the codebase, confirming they are accounted for. Omit this section if no existing artifacts.}

- ADR-XXXX: {title} -- covers {what area}
- SPEC-XXXX: {title} -- covers {what area}

### Next Steps

Pick the suggestions you want to formalize:

{For each high-confidence suggestion, repeat the command:}

/sdd:adr {description} /sdd:spec {capability}


Or prime your session with existing context first: `/sdd:prime`

Empty Results​

If no suggestions are found:

## Discovery Report

Analyzed {scope or "entire project"}: {N} files across {M} directories.
No implicit architectural decisions or spec-worthy subsystems were identified.

This may indicate:
- The project is very small or early-stage
- The codebase uses highly conventional patterns that don't require explicit documentation
- A narrower scope might reveal more specific patterns: `/sdd:discover src/`

### Next Steps
- Create your first ADR manually: `/sdd:adr [description]`
- Create your first spec manually: `/sdd:spec [capability]`

Example Invocations​

discover the implicit architecture in this legacy codebase
/sdd:discover
reverse-engineer ADRs from this existing repo
I inherited this code; figure out the architectural decisions baked in
what implicit invariants does this code enforce? extract them as candidate ADRs