Cursor rule

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