Windsurf rules

1---
2name: search-skills
3model: haiku
4description: "Find the right bigpowers skill from natural-language intent using a local lexical index over SKILL.md frontmatter. Use when unsure which skill to invoke, or at start of research-first."
5---
6 
7# story: e09s01
8# story: e21s01
9 
10# Search Skills
11 
12> **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
13>
14> **HARD GATE** — Do NOT use external embedding APIs or AI-based semantic search. This is a lexical-only index (ADR: zero external dependency).
15 
16Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX_LATEST.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
17 
18## When to use
19 
20- You're unsure which skill to invoke for a user's request
21- At the start of `research-first` to find pre-existing skills that might solve the problem
22- When a user asks "is there a skill for X?"
23- Before calling a skill by name, to confirm it's the right one
24 
25## Pre-flight
26 
27- [ ] Does `specs/SKILL-SEARCH-INDEX_LATEST.md` exist? If not, run `bash scripts/build-skill-index.sh`.
28- [ ] Is the index fresh? Check its timestamp — if > 24 hours old or after any SKILL.md change, regenerate.
29 
30## Process
31 
321. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX_LATEST.md` doesn't exist or was modified before the last SKILL.md change.
33 
342. **Search the index** — Use ripgrep on the lexical index:
35```
36   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX_LATEST.md
37```
38   The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
39 
403. **Rank results** — Read the top 3 matches. Evaluate by:
41   - **Exactness** — Does the description literally match the user's intent?
42   - **Phase fit** — Is the skill designed for the current lifecycle phase?
43   - **Trigger phrases** — Does the skill's "Use when" section match the situation?
44 
454. **Recommend one skill** — Select the single best-matching skill. Provide:
46   - The skill name
47   - Why it's the best match (citing the description or trigger phrase)
48   - What it produces (artifact, dialogue, or state change)
49 
505. **Invoke** — Call the skill directly or through the orchestrator. If no match found, suggest the closest phase-appropriate skill or `using-bigpowers` as a general entry point.
51 
52## Index Format
53 
54`specs/SKILL-SEARCH-INDEX_LATEST.md` contains one section per skill:
55```markdown
56## <skill-name>
57- **Description:** <from frontmatter>
58- **Phase:** <lifecycle phase>
59- **Triggers:** <key phrases from description>
60- **Keywords:** <extracted terms>
61```
62 
63## Why Not Semantic Search?
64 
65- Zero network dependency — works fully offline
66- Zero cost — no API keys, no usage limits
67- Instant — ripgrep on a local file is sub-second
68- Deterministic — same query always returns same results
69- Auditable — you can read the full index
70 
71## Verify
72 
73→ verify: `test -f specs/SKILL-SEARCH-INDEX_LATEST.md || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX_LATEST.md)`
74