KB Query Skill

Purpose

Interactive Knowledge Base search with natural language queries, providing fast access to institutional knowledge through relevance-ranked results with quality scoring.

How It Works

Step 1: Accept Query

User provides search query or problem description:

User: "Search KB for database connection pool issues"

Step 2: Execute Search

Run KB search with intelligent parameters:

# Basic search
make kb-search QUERY="database connection pool"

# With category filter
make kb-search QUERY="JWT authentication" CATEGORY=AUTH

# With quality threshold
make kb-search QUERY="performance optimization" MIN_SCORE=70

# All parameters
make kb-search QUERY="redis cache" CATEGORY=CACHE MIN_SCORE=60 LIMIT=10

Step 3: Display Results

Show top results with relevance and quality scores:

Search Results for "database connection pool"

Found 3 patterns:

1. DB-005: PostgreSQL Connection Pool Optimization
   Category: DB | Quality: 85/100 | Relevance: 9.2/10
   Keywords: postgresql, connection-pool, optimization, performance
   Problems solved:
   - Connection pool exhaustion under load
   - Slow query performance due to connection limits

2. PERF-002: Connection Pool Tuning Guide
   Category: PERF | Quality: 78/100 | Relevance: 8.5/10
   Keywords: connection-pool, tuning, performance, scalability
   Problems solved:
   - Optimizing pool size for workload
   - Monitoring pool utilization

3. DB-002: Database Connection Retry Logic
   Category: DB | Quality: 72/100 | Relevance: 7.1/10
   Keywords: database, connection, retry, error-handling
   Problems solved:
   - Transient connection failures
   - Graceful degradation on DB issues

Step 4: Offer Actions

Interactive follow-up options:

Actions:
1. View full content of a pattern (enter 1-3)
2. Search with different parameters
3. Browse by category
4. Exit

Your choice:

Step 5: View Full Content (if requested)

Display complete pattern details:

# Read full pattern file
cat docs/kb/patterns/DB-005-postgresql-connection-pool.md

Show structured content:

# DB-005: PostgreSQL Connection Pool Optimization

## Metadata
- Category: DB
- Quality Score: 85/100
- Created: 2025-10-15
- Author: senior-backend-engineer
- Time to solve: 120 minutes
- Complexity: Medium

## Problems This Solves
1. Connection pool exhaustion under load
2. Slow query performance due to connection limits
3. Connection timeout errors during peak traffic

## Solution

### Root Cause
Connection pool size (default: 10) insufficient for concurrent load (50+ requests/sec).

### Implementation
```javascript
// PostgreSQL pool configuration
const pool = new Pool({
  max: 50,              // Increase from default 10
  min: 10,              // Maintain minimum connections
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000,
});

// Add pool monitoring
pool.on('error', (err, client) => {
  console.error('Pool error:', err);
});

Validation Checklist

[ ] Pool size matches concurrent request load
[ ] Idle timeout configured to prevent stale connections
[ ] Connection timeout set for fail-fast behavior
[ ] Pool monitoring/alerting enabled
[ ] Load testing confirms no exhaustion

Related Patterns

PERF-002: Connection Pool Tuning Guide
DB-002: Database Connection Retry Logic
INFRA-003: Database Scaling Strategies

Tags

#postgresql #connection-pool #optimization #performance #database


## Search Parameters

### Query (Required)
Natural language search terms:
- Error messages: "ECONNREFUSED"
- Problem descriptions: "slow database queries"
- Technology + issue: "JWT token expired"
- Keywords: "authentication", "caching", "optimization"

### Category (Optional)
Filter by specific category:
- **ARCH**: Architecture and design patterns
- **DB**: Database patterns
- **API**: API design and integration
- **AUTH**: Authentication and authorization
- **SECURITY**: Security best practices
- **TEST**: Testing patterns
- **PERF**: Performance optimization
- **FRONTEND**: Frontend patterns
- **INFRA**: Infrastructure patterns
- **DEPLOY**: Deployment patterns
- **CACHE**: Caching strategies
- **MCP**: MCP server patterns
- **CLIENT**: Client integration patterns
- **FLOW**: Workflow and process patterns

### MIN_SCORE (Optional)
Minimum quality score (0-100):
- **80+**: Exceptional quality (comprehensive, validated)
- **60-79**: High quality (production-ready)
- **40-59**: Medium quality (usable, may need improvements)
- **<40**: Low quality (review before use)

Default: 60 (high quality only)

### LIMIT (Optional)
Maximum results to return (default: 5)

### Fuzzy Matching
Automatically enabled for typo tolerance:
- "databse" → "database"
- "authentiction" → "authentication"
- "conection" → "connection"

## Examples

### Example 1: Database Error Search

**Query**: "ECONNREFUSED connecting to PostgreSQL"

**Command**:
```bash
make kb-search QUERY="ECONNREFUSED PostgreSQL" CATEGORY=DB

Results:

Found 2 results:

1. BUG-002: PostgreSQL Connection Refused
   Type: Bug Fix | Relevance: 9.5/10
   Error: ECONNREFUSED, Could not connect to PostgreSQL
   Technologies: postgresql, docker, networking
   Fix Type: Configuration | Difficulty: Easy

2. DB-002: Database Connection Retry Logic
   Category: DB | Quality: 72/100 | Relevance: 6.8/10
   Keywords: database, connection, retry, error-handling

Action: View BUG-002 for exact fix steps

Example 2: Architecture Pattern Discovery

Query: "How to structure API endpoints for multi-tenant app"

Command:

make kb-search QUERY="multi-tenant API architecture" CATEGORY=ARCH MIN_SCORE=70

Results:

Found 3 patterns:

1. ARCH-004: Multi-Tenant API Design Patterns
   Category: ARCH | Quality: 88/100 | Relevance: 9.7/10

2. API-007: Tenant Isolation Strategies
   Category: API | Quality: 82/100 | Relevance: 8.9/10

3. DB-011: Multi-Tenant Database Schema Design
   Category: DB | Quality: 76/100 | Relevance: 7.5/10

Action: View ARCH-004 for comprehensive design approach

Example 3: No Results Found

Query: "quantum blockchain AI optimization"

Command:

make kb-search QUERY="quantum blockchain AI" MIN_SCORE=60

Results:

No results found for "quantum blockchain AI"

Suggestions:
1. Try broader search terms
2. Remove technical jargon
3. Search by specific error message
4. Browse categories: make kb-help
5. Create new pattern: make kb-pattern

Would you like to:
- Retry search with different terms? (r)
- Browse by category? (b)
- Create new pattern? (c)
- Exit? (e)

Example 4: Category Browse

Query: "Show all authentication patterns"

Command:

make kb-search QUERY="*" CATEGORY=AUTH

Results:

All AUTH patterns (7 total):

1. AUTH-001: JWT Token Authentication
   Quality: 92/100 | Problems: 3 | Code examples: 5

2. AUTH-003: OAuth 2.0 Implementation
   Quality: 88/100 | Problems: 4 | Code examples: 7

3. AUTH-005: Session Management Best Practices
   Quality: 85/100 | Problems: 3 | Code examples: 4

... (4 more patterns)

Error Handling

No Results

No results found for "your query"

This might mean:
- Pattern doesn't exist yet - create one with `make kb-pattern`
- Query too specific - try broader terms
- Typo in category name - available: ARCH, DB, API, AUTH, etc.

KB Not Indexed

Error: KB index not found

Run: make kb-index

This will scan all patterns and build the search index.

Invalid Category

Error: Invalid category "DATABAS"

Valid categories:
ARCH, DB, API, AUTH, SECURITY, TEST, PERF, FRONTEND,
INFRA, DEPLOY, CACHE, MCP, CLIENT, FLOW

Example: make kb-search QUERY="your query" CATEGORY=DB

Integration

Uses

Bash: Execute make kb-search commands
Read: Display full pattern content
Grep: Find related patterns by keyword
Glob: Browse patterns by category

References

docs/kb/KB.md: KB quick start guide
docs/kb/INDEX.md: Organized pattern index
docs/agents/KB-USAGE-GUIDE.md: Search workflow and API reference

Related Skills

kb-create: Create new patterns after search fails
root-cause-analyzer: Use KB results during 5 Whys analysis
debugger: Search KB before debugging

Workflow Summary

Accept user query (natural language or keywords)
Execute KB search with appropriate parameters
Display top 3-5 results with scores and metadata
Offer interactive actions:
- View full content
- Refine search
- Browse categories
- Create new pattern (if no results)
Follow up based on user choice

Tips for Effective Searching

Use Specific Keywords

Good: "JWT token expired 401"
Bad: "authentication doesn't work"

Include Technology Names

Good: "PostgreSQL connection pool exhaustion"
Bad: "database is slow"

Copy Exact Error Messages

Good: "ECONNREFUSED"
Bad: "connection error"

Filter by Category

Narrows results to relevant domain
Faster than browsing all patterns

Adjust Quality Threshold

Start with MIN_SCORE=60 (default)
Lower to 40 for broader results
Raise to 80 for only best patterns

Success Criteria

Search completes in <3 seconds
Relevance ranking surfaces best match first
Quality scores help assess pattern reliability
Fuzzy matching handles typos gracefully
Interactive actions provide clear next steps
Error messages are actionable and helpful

kb-query

KB Query Skill

Purpose

How It Works

Step 1: Accept Query

Step 2: Execute Search

Step 3: Display Results

Step 4: Offer Actions

Step 5: View Full Content (if requested)

Validation Checklist

Related Patterns

Tags

Example 2: Architecture Pattern Discovery

Example 3: No Results Found

Example 4: Category Browse

Error Handling

No Results

KB Not Indexed

Invalid Category

Integration

Uses

References

Related Skills

Workflow Summary

Tips for Effective Searching

Use Specific Keywords

Include Technology Names

Copy Exact Error Messages

Filter by Category

Adjust Quality Threshold

Success Criteria