Skip to main content

​
Overview

Search SDD artifacts by text, ID, type, or domain. Returns matching artifacts with relevance scores. Use to find requirements, use cases, tasks, or any pipeline artifact. The query tool uses a scoring algorithm that prioritizes exact ID matches, followed by partial ID matches, title matches, file path matches, code references, test references, and category matches.

​
Parameters

​
query
string
required
Search text — matches against artifact ID, title, file path, and code/test refs
​
type
string
Filter by artifact type: REQ, UC, WF, API, BDD, INV, ADR, NFR, RN, FASE, TASK
​
domain
string
Filter by business domain (e.g. ‘Security & Auth’, ‘Frontend & UI’)
​
limit
number
default:"20"
Max results to return

​
Response

​
query
string
The search query that was executed
​
filters
object
Applied filters
​
type
string | null
Type filter if applied
​
domain
string | null
Domain filter if applied
​
matches
number
Number of matching artifacts returned
​
totalCandidates
number
Total number of artifacts searched
​
results
array
Array of matching artifacts, sorted by relevance score
​
id
string
Artifact ID
​
type
string
Artifact type (REQ, UC, BDD, etc.)
​
title
string
Artifact title
​
file
string
Source file path
​
score
number
Relevance score (higher is better)
​
matchReasons
string[]
Reasons for the match (e.g. “exact ID match”, “title match”, “code ref: function in file.ts”)
​
hasCode
boolean
Whether artifact has code references
​
hasTests
boolean
Whether artifact has test references
​
hasCommits
boolean
Whether artifact has commit references

​
Scoring algorithm

The tool uses a weighted scoring system:
  • Exact ID match: 100 points
  • Partial ID match: 60 points
  • Title match: 40 points
  • Code reference match: 30 points
  • Test reference match: 25 points
  • File path match: 20 points
  • Category match: 15 points

​
Examples

​
Search for authentication requirements

{
  "query": "authentication",
  "type": "REQ"
}

​
Find a specific artifact by ID

{
  "query": "REQ-AUTH-001"
}

​
Search within a business domain

{
  "query": "user login",
  "domain": "Security & Auth",
  "limit": 10
}

​
Find artifacts referencing specific code

{
  "query": "authenticateUser"
}

​
TypeScript types

interface QueryArgs {
  query: string;
  type?: string;
  domain?: string;
  limit?: number;
}

interface ScoredArtifact {
  artifact: Artifact;
  score: number;
  matchReasons: string[];
}

​
See also

  • sdd_context - Get complete details for a specific artifact
  • sdd_coverage - Analyze coverage gaps across the pipeline

Build docs developers (and LLMs) love

Get started for freeTalk to us