search

What this skill does

# Unified Semantic Search

Search ADRs, specs, and code simultaneously using qmd hybrid retrieval, then enrich results with cgg call graphs for deeper code exploration.

## Process

<!-- Governing: ADR-0033 (cgg call graph integration), ADR-0024 (qmd as hard dependency), SPEC-0034 REQ "Hybrid Retrieval Across All Collections", SPEC-0034 REQ "Call Graph Generation Uses cgg With Filtering" -->

0. **Handle no-args / --help**: If `$ARGUMENTS` is empty or contains `--help`, output the usage block below and stop:

   ```
   Usage: /sdd:search <query> [--output markdown|json] [--unfiltered] [--module <name>]

   Examples:
     /sdd:search "JWT authentication"
     /sdd:search "payment processing" --output json
     /sdd:search "token validation" --unfiltered
     /sdd:search "auth middleware" --module api

   Searches ADRs, specs, and code with qmd hybrid retrieval, then generates
   call graphs with cgg for the most relevant code matches.
   ```

1. **Parse arguments**: Extract from `$ARGUMENTS`:
   - `<query>`: everything before any `--` flags (required; stop here if empty after flag extraction)
   - `--output markdown|json`: output format (default: `markdown`)
   - `--unfiltered`: when present, skip filter derivation and pass raw query keywords to cgg
   - `--module <name>`: when present, scope all collections and cgg to that module

2. **Compute the repo slug and collection names**:

   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-helpers Reference" -->

   Compute the slug per `references/qmd-helpers.md` § "This-Repo Collection Identification":

   ```bash
   SLUG=$(git rev-parse --show-toplevel | xargs basename | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g')
   ```

   - **Standard mode** (no `--module`): target collections `{slug}-adrs`, `{slug}-specs`, `{slug}-code`
   - **Workspace mode** (`--module <name>` provided): target collections `{slug}-{module}-adrs`, `{slug}-{module}-specs`, `{slug}-{module}-code`

3. **Validate qmd collections exist**:

   Use `mcp__plugin_qmd_qmd__status` (or `qmd status --json` as CLI fallback per `references/qmd-helpers.md` § "MCP-vs-CLI Selection") to list available collections. Apply exact-prefix match from `references/qmd-helpers.md` § "This-Repo Collection Identification".

   If none of the three target collections exist, stop with: "No qmd collections found for {repo}. Run `/sdd:index` first."

   Note which collections are missing (e.g., only `-adrs` and `-specs` but not `-code`) — search only what exists.

4. **Run qmd hybrid retrieval**:

   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0034 REQ "Hybrid Retrieval Across All Collections" -->

   Issue three separate qmd queries — one per collection type — so that ADR, spec, and code results are already partitioned when building output sections. Use MCP tool `mcp__plugin_qmd_qmd__query` (preferred) or `qmd query --json` as CLI fallback.

   **ADR query** (if `{slug}-adrs` or `{slug}-{module}-adrs` collection exists):
   ```
   searches: [
     { type: "lex", query: "<query verbatim>" },
     { type: "vec", query: "Architecture decisions about <query>" }
   ],
   intent: "/sdd:search — find ADRs relevant to: <query>",
   collections: ["{slug}-adrs"],    // or {slug}-{module}-adrs
   limit: 8,
   minScore: 0.3
   ```

   **Spec query** (if `{slug}-specs` or `{slug}-{module}-specs` collection exists):
   ```
   searches: [
     { type: "lex", query: "<query verbatim>" },
     { type: "vec", query: "Specifications and requirements for <query>" }
   ],
   intent: "/sdd:search — find specs relevant to: <query>",
   collections: ["{slug}-specs"],    // or {slug}-{module}-specs
   limit: 8,
   minScore: 0.3
   ```

   **Code query** (if `{slug}-code` or `{slug}-{module}-code` collection exists):
   ```
   searches: [
     { type: "lex", query: "<query verbatim>" },
     { type: "vec", query: "Source code implementing <query>" }
   ],
   intent: "/sdd:search — find code relevant to: <query>",
   collections: ["{slug}-code"],    // or {slug}-{module}-code
   limit: 8,
   minScore: 0.3
   ```

   Filter each result set: keep only items with `score >= 0.3`. Collect the three partitioned result sets.

   **No-matches path**: If all three queries return zero results above `minScore`, output the following and stop — do NOT proceed to cgg:

   ```
   No relevant ADRs, specs, or code found for '{query}'. Try a broader search term.
   ```

5. **Derive cgg filter** (unless `--unfiltered` was passed):

   <!-- Governing: ADR-0033 (cgg call graph integration), SPEC-0034 REQ "Call Graph Generation Uses cgg With Filtering" -->

   From the code query results, extract filter tokens per `references/cgg-integration.md` § "Filter Derivation Strategy — From qmd code matches":

   1. Take each matched file path stem (e.g., `auth/jwt.go` → `jwt`, `auth`)
   2. Take each qmd-matched symbol or heading keyword surfaced in the result snippets
   3. Compose a regex alternation: `token1|token2|token3`

   If the code query returned no results (collection absent or zero matches), fall back to keyword-based derivation per `references/cgg-integration.md` § "Filter Derivation Strategy — From requirement keywords":
   - Lowercase and split the query on spaces/punctuation
   - Strip common stop words (`the`, `a`, `an`, `for`, `with`, `of`, `in`, `and`, `or`, `to`)
   - Compose alternation from remaining terms

   If `--unfiltered` was passed, skip this step entirely. Warn the user:
   ```
   Generating unfiltered call graph — output may be large. Use /cgg directly for advanced scoping.
   ```

6. **Generate call graph with cgg**:

   <!-- Governing: ADR-0033 (cgg call graph integration), SPEC-0034 REQ "Call Graph Generation Uses cgg With Filtering", SPEC-0034 REQ "Error Messages and Logs Must Be Clear" -->

   Follow `references/cgg-integration.md` § "Availability Check" first:

   ```bash
   which cgg >/dev/null 2>&1
   ```

   If cgg is not found, record the unavailability notice and skip to step 7 (graceful degradation).

   Determine the target path:
   - Standard mode: repo root (`git rev-parse --show-toplevel`)
   - Workspace mode (`--module <name>`): resolve module source dir per `references/shared-patterns.md` § "Artifact Path Resolution"

   Invoke cgg per `references/cgg-integration.md` § "cgg Invocation Pattern":

   ```bash
   # With filter:
   timeout 30 cgg <target-path> --filter "<filter-regex>" --format mermaid 2>/tmp/cgg-stderr-$$.txt
   # Without filter (--unfiltered):
   timeout 30 cgg <target-path> --format mermaid 2>/tmp/cgg-stderr-$$.txt
   CGG_EXIT=$?
   CGG_STDERR=$(cat /tmp/cgg-stderr-$$.txt)
   rm -f /tmp/cgg-stderr-$$.txt
   ```

   Handle exit codes per `references/cgg-integration.md` § "Exit code handling":
   - Exit 0: normalize the Mermaid output per `references/cgg-integration.md` § "Mermaid Output Normalization"
   - Exit 1: record "Call graph generation failed: {stderr}" and skip to step 7
   - Exit 124: record timeout message per `references/cgg-integration.md` § "Timeout Handling" and skip to step 7
   - Other exit: treat as exit 1

   Apply node cap: if the Mermaid output has more than 20 nodes (lines matching `^\s+\w+\[`), trim to top 20 by connectivity and add the trimming comment per `references/cgg-integration.md` § "Node cap".

   Normalize output per `references/cgg-integration.md` § "Mermaid Output Normalization":
   - Sort nodes alphabetically
   - Rewrite `graph LR` or `graph RL` to `graph TD`
   - Strip memory-address node ID prefixes
   - Append legend footer `%% Showing entry points + main flow; internal helpers omitted`
   - Validate all `-->` edges reference declared nodes; remove dangling edges

   Handle unsupported-language warnings per `references/cgg-integration.md` § "Unsupported Language Handling".

7. **Produce output**:

   <!-- Governing: SPEC-0034 REQ "Markdown Output Format", SPEC-0034 REQ "JSON Output Format" -->

   **Markdown output** (default, or `--output markdown`):

   ```markdown
   ## S