Targeted query capabilities for machine-readable codebase documentation with cross-reference tracking, call graph analysis, and workflow automation. Enables fast lookups of classes, functions, dependencies, and function relationships without parsing source code.
The Skill(sdd-toolkit:doc-query) skill provides targeted query capabilities for machine-readable codebase documentation generated by the sdd doc generate command. It enables fast, structured lookups of classes, functions, modules, dependencies, and complexity metrics without parsing source code directly, plus advanced cross-reference tracking and call graph analysis.
describe-module surfaces docstrings, hot spots, dependencies, and key entities in one callNew to doc-query? Start with the scope command for comprehensive module analysis:
# Get focused context for planning a change
sdd doc scope <module_path> --plan
# Get focused context for implementing a change
sdd doc scope <module_path> --implement --function <function_name>
The scope command provides tailored information for different workflows:
--plan: Module summary, complexity analysis, and architectural overview--implement: Function callers, call graphs, and class usage patternsFor deeper analysis, use these automated workflow commands:
# Understand how a feature works end-to-end
sdd doc trace-entry <function_name>
# See what breaks if you change a function
sdd doc impact <function_name>
# Find high-priority refactoring candidates
sdd doc refactor-candidates
# Track how data flows through your system
sdd doc trace-data <ClassName>
These workflow commands combine 6-8 manual steps into single operations with intelligent analysis and risk assessment.
For specific lookups, use basic commands:
sdd doc find-function <name> - Locate a functionsdd doc callers <function> - See who calls this functionsdd doc call-graph <function> - Visualize call relationshipssdd doc dependencies <module> --reverse - Impact analysisSee below for complete command reference and advanced usage patterns.
Skill(sdd-toolkit:doc-query) when:Skill(sdd-toolkit:doc-query) when:sdd doc generate first)Explore or Read tool instead)Note: Documentation staleness is automatically detected and docs are auto-regenerated by default if out of date. Use --skip-refresh for faster queries without regeneration or --no-staleness-check to skip staleness detection entirely.
Use these workflows to systematically explore any codebase. All workflows are codebase-agnostic and work across languages, frameworks, and architectures.
| Workflow | Automated Command | Manual Alternative | When to Use It |
|----------|-------------------|-------------------|----------------|
| TRACE-ENTRY-POINT | trace-entry <function> | 6-step pattern | "How does [action] work?" |
| TRACE-DATA-OBJECT | trace-data <class> | 6-step pattern | "What happens to [entity]?" |
| IMPACT-ANALYSIS | impact <entity> | 7-step pattern | "What breaks if I modify X?" |
| REFACTOR-PRIORITY | refactor-candidates | Manual complexity analysis | "What should I refactor first?" |
| EXPLORE-FEATURE-AREA | Use context + manual queries | 5-step pattern | "Tell me about the [feature] system" |
| FIND-PATTERN | Manual queries only | 6-step pattern | "How do we do [validation/auth/caching]?" |
| ONBOARD-TO-CODEBASE | Manual queries only | 6-step pattern | "I'm new here, where do I start?" |
| TRACE-ERROR-FLOW | Manual queries only | 5-step pattern | "How are errors handled?" |
| TRACE-CONFIGURATION | Manual queries only | 5-step pattern | "Where is [config/flag] used?" |
| TRACE-TEST-COVERAGE | Manual queries only | 5-step pattern | "What tests cover [feature]?" |
Note: Workflows with automated commands (top 4) reduce 6-7 manual steps to 1 command. Others require manual query composition using basic commands.
START: What do you want to know?
│
├─ "How does [action/request/event] work?"
│ └─ sdd doc trace-entry <function> [AUTOMATED]
│
├─ "What happens to [data/entity]?"
│ └─ sdd doc trace-data <class> [AUTOMATED]
│
├─ "What breaks if I change [X]?"
│ └─ sdd doc impact <entity> [AUTOMATED]
│
├─ "What should I refactor?"
│ └─ sdd doc refactor-candidates [AUTOMATED]
│
├─ "Tell me about [feature/module/system]"
│ └─ sdd doc context + manual queries [MANUAL]
│
├─ "How do we do [pattern] here?" (e.g., validation, auth, caching)
│ └─ Manual query pattern (see below) [MANUAL]
│
├─ "I'm new here, where do I start?"
│ └─ Manual onboarding pattern (see below) [MANUAL]
│
├─ "How are errors handled?"
│ └─ Manual error tracing pattern (see below) [MANUAL]
│
├─ "Where is [config/flag] used?"
│ └─ Manual config tracing pattern (see below) [MANUAL]
│
└─ "What tests cover [feature]?"
└─ Manual test coverage pattern (see below) [MANUAL]
Tier 1: Automated Workflows (One-command solutions for common tasks)
trace-entry - Understand execution flow end-to-endtrace-data - Follow data lifecycle through systemimpact - Assess blast radius of changesrefactor-candidates - Identify technical debt prioritiesTier 2: Manual Query Patterns (Advanced usage for specialized needs)
Before using this skill, verify the required tools are available:
# Verify sdd doc CLI is installed and accessible
sdd doc --help
Expected output: Help text showing available commands (stats, search, find-class, describe-module, etc.)
IMPORTANT - CLI Usage Only:
sdd doc CLI wrapper commands (e.g., sdd doc stats, sdd doc search, sdd doc find-class)python doc_query.py, bash python cli.py)The CLI provides proper error handling, validation, argument parsing, and interface consistency. Direct script execution bypasses these safeguards and may fail.
If the verification command fails, ensure the SDD toolkit is properly installed and accessible in your environment.
sdd doc generatedocs/ directory:
codebase.json (required)index.md (optional, navigation hub)project-overview.md (optional, executive summary)architecture.md (optional, system design)component-inventory.md (optional, component catalog)Note: You should NOT read the codebase.json document manually.
sdd doc CLI automatically searches for documentation in multiple locations (in order of priority):
./docs/../docs/./documentation/~/.claude/docs/No --docs-path needed for most cases! The tool will find your documentation automatically.
Explicit path override: Use --docs-path PATH to specify a custom location:
sdd doc stats --docs-path /path/to/project/docs
Check detection: The stats command shows which path was detected:
sdd doc stats
# Output includes: "Found documentation at: /path/to/docs"
NEW: doc-query now automatically detects and regenerates stale documentation by default!
Every query command automatically checks if source files have been modified since documentation was generated:
$ sdd doc find-function calculate_score
🔄 Documentation is stale, regenerating...
✅ Documentation regenerated successfully
Found 1 result(s):
...
--skip-refresh: Skip Auto-RegenerationSkips auto-regeneration even if docs are stale, showing only a warning:
$ sdd doc find-function calculate_score --skip-refresh
⚠️ Documentation is stale (generated 3 days ago, source modified 2 hours after generation)
To auto-refresh: remove --skip-refresh flag or run 'sdd doc generate'
To suppress this warning: use --no-staleness-check
Found 1 result(s):
...
When to use:
--no-staleness-check: Skip Check EntirelyDisables staleness detection completely for maximum speed:
$ sdd doc find-function calculate_score --no-staleness-check
Found 1 result(s):
...
When to use:
Workflow 1: Default behavior (recommended)
# Automatically regenerates if needed - guaranteed fresh results
sdd doc impact UserService
Workflow 2: Fast exploration
# Skip regeneration for quick lookups
sdd doc find-class User --skip-refresh
sdd doc describe-module auth.py --skip-refresh
Workflow 3: Maximum performance
# Skip staleness check entirely
sdd doc search "validation" --no-staleness-check
These commands automate common workflows by combining multiple queries into single, purpose-built commands. Use these first for the fastest results.
Trace execution flow from an entry function, showing the complete call chain with architectural layers and complexity analysis.
sdd doc trace-entry <function> [--max-depth N] [--docs-path PATH]
Options:
--max-depth N - Maximum call chain depth (default: 5)Examples:
# Trace execution flow from main
sdd doc trace-entry main
# Trace with custom depth
sdd doc trace-entry process_request --max-depth 3
Output includes:
When to use:
Trace how a data object (class) flows through the codebase, showing CRUD operations and usage patterns.
sdd doc trace-data <classname> [--include-properties] [--docs-path PATH]
Options:
--include-properties - Include detailed property access analysisExamples:
# Trace User class lifecycle
sdd doc trace-data User
# Include property access patterns
sdd doc trace-data User --include-properties
Output includes:
When to use:
Analyze the impact of changing a function or class, calculating the blast radius with risk assessment.
sdd doc impact <entity> [--depth N] [--docs-path PATH]
Options:
--depth N - Maximum depth for indirect dependency traversal (default: 2)Examples:
# Analyze impact of changing a function
sdd doc impact calculate_score
# Deep analysis with 3 levels
sdd doc impact UserService --depth 3
Output includes:
When to use:
Find high-priority refactoring candidates by combining complexity metrics with usage data.
sdd doc refactor-candidates [--min-complexity N] [--limit N] [--docs-path PATH]
Options:
--min-complexity N - Minimum complexity threshold (default: 10)--limit N - Maximum number of candidates to return (default: 20)Examples:
# Find refactoring candidates
sdd doc refactor-candidates
# Focus on high-complexity functions
sdd doc refactor-candidates --min-complexity 20 --limit 10
Output includes:
When to use:
These commands provide targeted lookups for specific entities and relationships. Combine them to build custom workflows when automated commands don't fit your needs.
Find a specific class by exact name or regex pattern.
sdd doc find-class <name> [--pattern] [--docs-path PATH]
Examples:
# Find exact class
sdd doc find-class WizardSession
# Find classes matching pattern
sdd doc find-class ".*Session.*" --pattern
When to use:
Find a specific function by exact name or regex pattern.
sdd doc find-function <name> [--pattern] [--docs-path PATH]
Examples:
# Find exact function
sdd doc find-function calculate_score
# Find functions matching pattern
sdd doc find-function ".*score.*" --pattern
When to use:
Produce a rich summary for a specific module, including docstring, key classes/functions, dependencies, and complexity signals.
sdd doc describe-module <module> [--top-functions N] [--include-docstrings] [--skip-dependencies] [--docs-path PATH]
Examples:
# Quick overview with defaults
sdd doc describe-module app/services/scoring.py
# Focus on the top 3 complex functions and include docstring snippets
sdd doc describe-module app/services/scoring.py --top-functions 3 --include-docstrings
# Export summary as JSON for downstream tooling
sdd doc describe-module scoring.py --json
When to use:
--jsonFind a module by name or pattern.
sdd doc find-module <name> [--pattern] [--docs-path PATH]
Examples:
# Find exact module
sdd doc find-module app/services/scoring.py
# Find modules matching pattern
sdd doc find-module ".*scoring.*" --pattern
When to use:
describe-moduleList functions above a complexity threshold.
sdd doc complexity [--threshold N] [--module M] [--docs-path PATH]
Examples:
# Find all functions with complexity >= 5
sdd doc complexity
# Find high-complexity functions (>= 8)
sdd doc complexity --threshold 8
# Find complex functions in a specific module
sdd doc complexity --module scoring.py
When to use:
Show module dependencies (direct or reverse).
sdd doc dependencies <module> [--reverse] [--docs-path PATH]
Examples:
# Show what a module imports
sdd doc dependencies app/services/scoring.py
# Show what imports this module (reverse dependencies)
sdd doc dependencies app/models/session.py --reverse
When to use:
How it works:
Important: Import Names vs File Paths
The dependency system tracks import strings as they appear in code, not normalized file paths.
✅ Forward dependencies work with file paths:
# This works - shows what this file imports
sdd doc dependencies src/myapp/services/auth.py
⚠️ Reverse dependencies require import names:
# ✅ CORRECT - Use the import name
sdd doc dependencies "myapp.services.auth" --reverse
sdd doc dependencies "auth" --reverse # May work for short names
# ❌ INCORRECT - File path won't match import strings
sdd doc dependencies src/myapp/services/auth.py --reverse
# Returns: No results (even if modules import this)
Why the difference?
When Python code imports a module:
from myapp.services.auth import login # Import string: "myapp.services.auth"
import myapp.services.auth # Import string: "myapp.services.auth"
The dependency tracker stores "myapp.services.auth" (the import string), not "src/myapp/services/auth.py" (the file path).
Finding the correct import name:
If you're not sure of the import name, use forward dependencies first:
# 1. Check what imports this module (look at the output)
sdd doc dependencies src/myapp/services/auth.py
# 2. Look for project-internal imports (not stdlib)
# Output might show: "myapp.models", "myapp.config", etc.
# 3. Use similar patterns for reverse lookups
sdd doc dependencies "myapp.services.auth" --reverse
Practical workflow for impact analysis:
# Step 1: Find the module you want to analyze
sdd doc find-module "auth" --pattern
# Step 2: Check forward deps (what it uses)
sdd doc dependencies src/myapp/services/auth.py
# Step 3: Infer import name from file structure
# File: src/myapp/services/auth.py
# Likely import: myapp.services.auth
# Step 4: Check reverse deps (who uses it)
sdd doc dependencies "myapp.services.auth" --reverse
# Step 5: Analyze the blast radius
# Combine results to understand full impact
Edge cases:
argparse, json): These will show reverse dependencies for all modules that import them__init__.py): These may not show direct imports if other modules import from the parent packagefrom . import foo): Stored as relative strings, may need exact matchShow functions that call the specified function using cross-reference data from AST analysis.
sdd doc callers <function> [--docs-path PATH]
Examples:
# Find all functions that call calculate_score
sdd doc callers calculate_score
# Find callers with specific path
sdd doc callers process_data --docs-path ./docs
Output includes:
When to use:
Show functions called by the specified function using cross-reference data from AST analysis.
sdd doc callees <function> [--docs-path PATH]
Examples:
# Find all functions called by main
sdd doc callees main
# Find callees with specific path
sdd doc callees process_request --docs-path ./docs
Output includes:
When to use:
Build and visualize function call graphs with configurable depth and direction.
sdd doc call-graph <function> [--depth N] [--direction up|down|both] [--docs-path PATH]
Options:
--depth N - Maximum graph depth (default: 3)--direction - Graph direction:
down: Show callees (functions this calls) - defaultup: Show callers (functions that call this)both: Show both callers and calleesExamples:
# Show call graph for a function (what it calls)
sdd doc call-graph process_request
# Show upstream callers (who calls this)
sdd doc call-graph calculate_score --direction up --depth 2
# Show bidirectional graph
sdd doc
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer