Problem
SDD phases that investigate the codebase (sdd-explore, sdd-apply, sdd-verify) rely on brute-force Grep+Read with no configurable search backend. Token consumption scales linearly with codebase size — there is no extension point to leverage semantic/vector code search via MCP RAG servers.
Currently:
sdd-phase-common.md has no section about code search
sdd-explore Step 3 is prose ("read entry points and key files")
sdd-apply Step 2 says "read existing code" with no mechanism
sdd-verify Step 4 says "search codebase for implementation evidence" with no mechanism
Proposal
Add a search_strategy config (top-level key alongside strict_tdd) with two modes:
| Mode |
Behavior |
grep |
Default. Current behavior — Grep + Read. Zero change for existing users. |
hybrid |
RAG-first cascade with grep fallback. Requires search_strategy.rag.mcp_tool. |
Hybrid cascade (each step strictly additive)
1. Semantic query → MCP RAG tool → relevant chunks
├── Sufficient (≥2 snippets)? → use them
└── Insufficient?
↓
2. Grep → exact symbol/pattern match
↓
3. Read → targeted line ranges (NOT full files)
Config schema
search_strategy:
mode: grep | hybrid
rag:
mcp_tool: "tool_name" # REQUIRED for hybrid
reindex_tool: "tool_name" # optional — fire-and-forget after sdd-apply batch
Design
Follows the strict_tdd pattern exactly:
- Auto-detected in
sdd-init (Step 3.5) — scans MCP tools, no interactive prompts
- Persisted in project context (engram or openspec/config.yaml)
- Each code-reading phase reads config and branches via shared Section E protocol
- Missing config =
grep = current behavior (zero regression)
Files affected
| File |
Change |
_shared/sdd-phase-common.md |
New Section E: Code Search Protocol |
_shared/persistence-contract.md |
search_strategy schema in sub-agent context |
sdd-init/SKILL.md |
Step 3.5 + config output + summary rows |
sdd-explore/SKILL.md |
Step 3 references Section E |
sdd-apply/SKILL.md |
Step 2 references Section E + reindex hook in Step 6 |
sdd-verify/SKILL.md |
Step 4 references Section E |
Out of scope
- Standalone
rag mode without grep fallback
- Multiple simultaneous RAG tools
- Embedding generation or vector DB management
Problem
SDD phases that investigate the codebase (
sdd-explore,sdd-apply,sdd-verify) rely on brute-force Grep+Read with no configurable search backend. Token consumption scales linearly with codebase size — there is no extension point to leverage semantic/vector code search via MCP RAG servers.Currently:
sdd-phase-common.mdhas no section about code searchsdd-exploreStep 3 is prose ("read entry points and key files")sdd-applyStep 2 says "read existing code" with no mechanismsdd-verifyStep 4 says "search codebase for implementation evidence" with no mechanismProposal
Add a
search_strategyconfig (top-level key alongsidestrict_tdd) with two modes:grephybridsearch_strategy.rag.mcp_tool.Hybrid cascade (each step strictly additive)
Config schema
Design
Follows the
strict_tddpattern exactly:sdd-init(Step 3.5) — scans MCP tools, no interactive promptsgrep= current behavior (zero regression)Files affected
_shared/sdd-phase-common.md_shared/persistence-contract.mdsdd-init/SKILL.mdsdd-explore/SKILL.mdsdd-apply/SKILL.mdsdd-verify/SKILL.mdOut of scope
ragmode without grep fallback