// 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.
Task preparation skill for spec-driven workflows. Reads specifications, identifies next actionable tasks, and creates detailed execution plans. Use when ready to implement a task from an existing spec - bridges the gap between planning and coding.
Validate SDD JSON specs, auto-fix common issues, generate detailed reports, and analyze dependencies.
LLM-powered documentation generation for narrative architecture docs, tutorials, and developer guides. Uses AI consultation to create contextual, human-readable documentation from code analysis and spec data.
Plan-first development methodology that creates detailed specifications before coding. Use when building features, refactoring code, or implementing complex changes. Creates structured plans with phases, file-level details, and verification steps to prevent drift and ensure production-ready code.
AI-powered PR creation after spec completion. Analyzes spec metadata, git diffs, commit history, and journal entries to generate comprehensive PR descriptions with user approval before creation.
Comprehensive pytest testing and debugging framework. Use when running tests, debugging failures, fixing broken tests, or investigating test errors. Includes systematic investigation workflow with external AI tool consultation and verification strategies.
| name | doc-query |
| description | 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 call-graph main --direction both --depth 3
Output includes:
When to use:
Search across all entities (classes, functions, modules).
sdd doc search <query> [--limit N] [--docs-path PATH]
Examples:
# Search for anything related to authentication
sdd doc search "auth"
# Search for scoring-related entities
sdd doc search "score.*"
# Limit results to first 10 matches
sdd doc search "CLI" --limit 10
When to use:
--limit to control output volume for broad searchesGather comprehensive context for a feature area.
sdd doc context <area> [--docs-path PATH]
Examples:
# Get all entities related to wizard functionality
sdd doc context "wizard"
# Get all scoring-related context
sdd doc context "scoring"
When to use:
Show documentation statistics and metrics.
sdd doc stats [--docs-path PATH]
When to use:
List all classes, functions, or modules.
sdd doc list-classes [--module M] [--docs-path PATH]
sdd doc list-functions [--module M] [--docs-path PATH]
sdd doc list-modules [--docs-path PATH]
Examples:
# List all classes
sdd doc list-classes
# List functions in a specific module
sdd doc list-functions --module scoring.py
# List all modules
sdd doc list-modules
When to use:
For specialized needs or custom analysis, you can manually combine basic query commands. The automated workflows (above) handle 90% of use cases, but these patterns provide fine-grained control when needed.
These workflows provide systematic approaches to understanding any codebase. All patterns use generic placeholders like [feature], [entity], [pattern] - substitute with your domain-specific terms.
Goal: Understand the end-to-end flow of a user action, API request, or system event.
Use cases: "How does the scoring process work?", "What happens when a user clicks 'Submit'?", "How are webhook events processed?"
sdd doc trace-entry <function_name> [--max-depth N]
Examples:
# Trace execution from FastAPI endpoint
sdd doc trace-entry process_scoring_request
# Trace with custom depth
sdd doc trace-entry handle_submit --max-depth 3
Output: Complete call chain, architectural layers, complexity analysis, hot spots
If you need fine-grained control or the function name is unknown:
# 1. Find entry point
sdd doc search "[endpoint|route|handler].*[feature]"
# 2. Get callers/callees
sdd doc callees <function> # or call-graph for visualization
# 3. Describe key modules
sdd doc describe-module <module>
Goal: Follow a specific data structure or entity through its lifecycle.
Use cases: "What happens to a User object?", "How is OrderData transformed?", "Where is ConfigSettings used?"
sdd doc trace-data <ClassName> [--include-properties]
Example: sdd doc trace-data User
Output: CRUD operations, usage map by layer, property access patterns
# 1. Find class definition
sdd doc find-class <ClassName>
# 2. Find instantiation sites
sdd doc call-graph <ClassName> --direction both
# 3. Search for usage patterns
sdd doc search "create.*[Entity]|update.*[Entity]"
Goal: Identify all code affected by modifying a function, class, or module.
Use cases: "What breaks if I refactor this function?", "What depends on this API endpoint?", "Can I safely delete this class?"
sdd doc impact <entity> [--depth N]
Example: sdd doc impact calculate_score --depth 2
Output: Direct/indirect dependents, test coverage estimate, risk score (high/medium/low), actionable recommendations
# 1. Find callers
sdd doc callers <function>
# 2. Find reverse dependencies
sdd doc dependencies <module> --reverse
# 3. Assess complexity
sdd doc complexity --module <module>
# 4. Check usage
sdd doc search "<exact-name>"
Note: For reverse dependencies, use import names not file paths (e.g., "myapp.utils.scoring" not utils/scoring.py). See "Understanding Reverse Dependencies" section.
Goal: Identify high-complexity, high-impact code for refactoring.
Use cases: "What should I refactor first?", Technical debt reduction planning
sdd doc refactor-candidates [--min-complexity N] [--limit N]
Example: sdd doc refactor-candidates --min-complexity 15
Output: Prioritized list by priority score (complexity × dependents), risk categorization, quick wins vs major refactors
# 1. Find high-complexity functions
sdd doc complexity --threshold 15
# 2. For each, assess impact
sdd doc callers <function>
sdd doc dependencies <module> --reverse
For specialized investigations without automated commands, combine basic queries:
Goal: Comprehensive feature context gathering
sdd doc context "[feature]" # Get all related entities
sdd doc describe-module [key-modules] # Understand each layer
sdd doc complexity | grep "[feature]" # Find hot spots
Goal: Discover how patterns (validation, caching, auth) are implemented
sdd doc search "[pattern-keyword]" # Find implementations
sdd doc find-class ".*[Pattern].*" --pattern # Find pattern classes
sdd doc describe-module [pattern-file] # Understand architecture
Goal: Get oriented in an unfamiliar codebase
sdd doc stats # Overview: size, complexity baseline
sdd doc search "main|index|app" # Find entry points
sdd doc list-modules # Understand architecture
sdd doc complexity --threshold 10 # Identify areas to avoid initially
Goal: Understand error propagation and handling
sdd doc find-class ".*Error.*|.*Exception.*" --pattern # Find error types
sdd doc search "raise|throw|except" # Find error handling
sdd doc describe-module [error-module] # Understand error architecture
Goal: Track configuration usage
sdd doc find-class "[Config|Settings].*" --pattern # Find config classes
sdd doc search "get_settings|config" # Find access patterns
sdd doc dependencies [config-module] --reverse # Find consumers
Goal: Understand testing strategy
sdd doc list-modules | grep "test" # Find test files
sdd doc describe-module tests/[feature]_test.py # Understand test structure
sdd doc dependencies tests/[test-file] # See what's being tested
Use automated workflows (trace-entry, trace-data, impact, refactor-candidates) when:
Use manual query patterns when:
Understand how the scoring feature works end-to-end:
sdd doc trace-entry run_scoring
Shows complete call chain from HTMX endpoint → scoring service → LLM service → OpenAI API, with architectural layer classification, complexity scores for each function, and hot spot identification.
Assess the blast radius before refactoring get_session function:
sdd doc impact get_session
Returns risk level CRITICAL (complexity 85 × 50+ dependents), lists direct and indirect dependents, estimates test coverage, and provides actionable recommendations for safe refactoring approach.
Identify high-priority technical debt:
sdd doc refactor-candidates --min-complexity 15
Returns prioritized list sorted by risk score (complexity × dependents), categorizes by risk level, identifies quick wins (high complexity, low dependents) vs major refactors (high complexity, high dependents), with specific recommendations for each.
For more information on generating documentation, see the Skill(sdd-toolkit:code-doc) skill.
For spec-driven development workflows, see Skill(sdd-toolkit:sdd-plan), Skill(sdd-toolkit:sdd-next), and Skill(sdd-toolkit:sdd-update) skills.