| name | design-search |
| description | Full-text search across design documentation. Use when looking for specific topics, decisions, or patterns documented across design docs. |
| allowed-tools | Read, Grep, Glob, Bash(grep *), Bash(xargs *), Bash(awk *), Bash(head *) |
| context | fork |
| agent | design-doc-agent |
Design Documentation Search
Searches across all design documentation to find relevant content, decisions,
and patterns.
Overview
This skill provides full-text search across all design docs with filtering,
ranking, and contextual results. Use it to quickly locate specific topics,
architectural decisions, implementation patterns, or TODO items across
the entire design documentation system.
Quick Start
Simple search:
/design-docs:design-search "observability"
Filtered search:
/design-docs:design-search "data flow" --category=architecture
Section-specific:
/design-docs:design-search "performance" --section=Rationale
Parameters
Required
query - Search query (keywords or phrase)
Optional
module - Limit to specific modulecategory - Filter by category (architecture, performance, etc.)status - Filter by status (stub, draft, current, etc.)section - Search only in specific sectionscontext - Lines of context to show (default: 2)
Workflow
High-level search process:
- Parse query and filters from user request
- Load design.config.json to identify target modules
- Find documents matching filters (module, category, status)
- Execute search using Grep with appropriate context
- Extract metadata from document frontmatter
- Rank results by relevance, status, location, and recency
- Format output with context, metadata, and navigation
- Suggest related docs based on cross-references
For detailed implementation steps, see supporting documentation below.
Supporting Documentation
When you need detailed information, load the appropriate supporting file:
For Detailed Workflow
See instructions.md for:
- Complete step-by-step search workflow
- Frontmatter parsing and metadata extraction
- Result ranking algorithm and scoring
- Navigation path generation
- Edge case handling (no results, too many results)
- Performance optimization strategies
- Output customization options
Load when: Performing search or need implementation details
For Query Syntax
See query-syntax.md for:
- Search strategies (keyword, multi-term, section-specific, metadata)
- Search patterns (find decisions, implementations, TODOs, trade-offs)
- Query operators (grep options, regex patterns)
- Best practices and performance tips
Load when: Performing complex searches or need query syntax reference
For Filter Options
See filter-options.md for:
- All filter parameters and their valid values
- Filtering process and frontmatter extraction
- Result ranking algorithm and factors
- Advanced features (cross-references, highlighting, grouping)
- Performance optimization techniques
Load when: Applying filters, ranking results, or need filtering details
For Usage Examples
See examples.md for:
- Complete search examples (simple, filtered, section-specific)
- Output format examples
- Multi-filter searches
- Special cases (no results, too many results)
- Finding decisions, implementations, and TODOs
Load when: User needs examples or clarification on search usage
Error Handling
No Results Found
INFO: No matches found for "{query}"
Suggestions:
- Try broader search terms
- Remove filters
- Check spelling
- Search for related terms
Too Many Results
WARNING: {count} results found (showing top 20)
Suggestions:
- Add filters (module, category, status)
- Use more specific search terms
- Search in specific section
Invalid Filter
ERROR: Invalid {filter-name}: "{value}"
Valid values: {valid-list}
Integration
Works well with:
/design-docs:design-review - Review docs found in search/design-docs:design-validate - Validate docs found/design-docs:design-link - See relationships between search results/design-docs:design-update - Update docs found in search
Success Criteria
A successful search:
- ✅ Finds all relevant matches
- ✅ Ranks results by relevance
- ✅ Provides sufficient context
- ✅ Shows document metadata
- ✅ Offers clear navigation paths
- ✅ Suggests related documents
