Semantic Search Service Workflow
Expert workflow for building and maintaining a semantic search service using LLM-native layered architecture (LNLA) principles.
Core Philosophy
This skill implements a research-first, test-driven approach to semantic search development with strict adherence to SOLID principles and DRY at the architectural level.
Critical Pre-Implementation Checks
**ALWAYS start by checking these files:**
1. **CAPABILITY_MAPPING.md** - Truth table of implemented vs claimed features
2. **CODE_QUALITY_AUDIT.md** - Current SOLID/DRY compliance status
3. **TASK.md** - Current sprint work and incomplete tasks
4. **VISION.md** - Feature tracking and roadmap
LNLA Workflow (Memory Signal Pattern)
Follow this workflow for EVERY implementation:
1. EXPLORE
Read codebase structure thoroughlyUnderstand where files belong based on folder organizationNever assume - always verify by reading existing files completely2. RESEARCH
Use Perplexity for modern implementation patternsCheck LlamaIndex indexed docs: `doc_search.py`Add `:research:` to prompt for automated semantic search (explicit trigger mode)Review existing solutions in codebase3. PLAN
List all requirements (API keys, dependencies, interfaces)Identify which layer handles each responsibilityMap out 95/5 delegation pattern4. TDD - Write Failing Test
Write test FIRST before any implementationTest must fail initially to prove it's testing something realUse real data/APIs in tests, not mocks5. RED - Confirm Test Fails
Run test and verify it fails as expectedThis prevents "completion theatre" (claiming success without working code)6. IMPLEMENT
Build feature to pass testFollow LNLA principles (see Architecture section)Inject dependencies - NEVER create inside classes7. GREEN - Verify Test Passes
Run test with real data/APIsVerify actual results, not just compilationTest must demonstrate working functionality8. COMMIT
Only commit working, tested codeUpdate all documentation (see Documentation Requirements)Architecture Principles
LLM-Native Layered Architecture (LNLA)
**Layer Structure** (each delegates 95% to layer below):
```
Business Logic ← 95% from Service Layer
Service Layer ← 95% from Core Layer
Core Layer ← 95% from LlamaIndex
LlamaIndex ← 95% from Libraries
```
**Core Rules:**
**<100 LOC per file** - Optimized for LLM context**<50 LOC for hooks** - Minimal trigger code only**One domain per file** - Clear boundaries**Zero variants** - No _v2, _new, _updated suffixes**Migration isolation** - Framework changes in 1-2 files maxDependency Injection Pattern (DIP)
**ALWAYS inject dependencies through constructor:**
```python
❌ WRONG: Hard dependency (not testable)
class KnowledgeGraph:
def __init__(self):
self.intelligence = get_codebase_intelligence()
✅ RIGHT: Dependency injection (testable)
class KnowledgeGraph:
def __init__(self, intelligence: IntelligenceInterface):
self.intelligence = intelligence
```
File Placement Rules
**Let structure guide you** - Folder organization determines placement**Update in place** - Same file, same names**NEVER create variants** - No v2, no alternatives**Centralized solutions** - DRY at architecture level**Directory Structure:**
`src/core/` - Core layer (prompts, index helpers)`src/components/` - Service layer components`src/integrations/` - External service integrations`scripts/` - Utilities and hooks`docs/` - DocumentationResearch Hook System (Experimental)
**Current Status**: Explicit trigger mode only (auto-research disabled due to performance)
**Usage**: Add `:research:` to your prompt:
```
:research: implement user authentication system
```
**Configuration** (`.clauderc.yaml`):
```yaml
research_hooks:
enabled: true
auto_research: false # Disabled - too slow currently
explicit_trigger: ":research:"
performance_threshold: 100 # Target: <100ms
cache_enabled: true
```
**Hook Scripts:**
`scripts/hooks/research_hook.py` - UserPromptSubmit research`scripts/hooks/validate_edit_hook.py` - PreToolUse validation`scripts/hooks/benchmark_research.py` - Performance testingDocumentation Requirements
After EVERY implementation, update ALL of these:
1. **TASK.md**
- Archive completed tasks
- Carry forward incomplete work
2. **VISION.md**
- Update capability table
- Mark features as implemented
3. **CAPABILITY_MAPPING.md**
- Update truth table (working vs claimed)
4. **CLAUDE.md**
- Update if workflow changes
5. **API_REFERENCE.md**
- Verify endpoints documented
Auto-Documentation System
**Setup** (one-time):
```bash
./scripts/setup_auto_docs.sh
```
**Manual generation**:
```bash
python src/core/auto_docs.py generate
```
Git hooks automatically update docs on commit.
Key Files Reference
`CAPABILITY_MAPPING.md` - Truth table of features`CODE_QUALITY_AUDIT.md` - SOLID/DRY status`src/core/index_helper.py` - DRY helper for index access`src/core/prompts.yaml` - Centralized prompts (OCP compliant)`src/core/prompts.py` - Prompt loader`docs/VISION.md` - Feature tracking`TASK.md` - Current sprint workTesting Requirements
**Tests MUST:**
✅ Return ACTUAL RESULTS (not just compile)✅ Use real data/APIs✅ Demonstrate working functionality❌ NOT claim success based on code generation alone**Test Pattern:**
1. Write test first (TDD)
2. Verify it fails (RED)
3. Implement feature
4. Verify it passes with real data (GREEN)
5. Only then commit
When Blocked
Follow this sequence:
1. **READ existing files FULLY** - Never assume content
2. **Check folder structure** - Let organization guide placement
3. **Search indexed docs**: `doc_search.py`
4. **Use Perplexity** for modern patterns
5. **STOP and ask user** - Zero assumptions allowed
Naming Conventions
✅ Update in place - same file, same names❌ NEVER use: _v2, _new, _updated suffixes❌ NEVER create: Multiple files for same purpose✅ Let structure guide namingCommit Rules
**ONLY commit when:**
✅ All tests pass✅ Feature fully working with real data✅ All documentation updated✅ Code follows LNLA principles✅ Dependencies properly injected**NEVER commit:**
❌ Broken code❌ "Partially working" features❌ Untested implementations❌ Hard-coded dependenciesQuality Standards
**Code must be:**
**<100 LOC per file** (LLM context optimized)**SOLID compliant** (especially DIP)**DRY at architecture level****95% framework delegation****Fully tested with real data**Example Implementation Flow
```
1. Check CAPABILITY_MAPPING.md + TASK.md
2. Add :research: to prompt for context
3. Write failing test with real API
4. Confirm test fails (RED)
5. Implement with dependency injection
6. Verify test passes (GREEN)
7. Update TASK.md, VISION.md, CAPABILITY_MAPPING.md
8. Commit working code
```
Success Criteria
Implementation is complete when:
✅ Tests pass with real data✅ Returns actual results (not just generates code)✅ All documentation updated✅ Follows LNLA principles✅ Uses dependency injection✅ No code duplication✅ <100 LOC per file