---
name: fp-search
description: Local full-text search across fastpace/context/, fastpace/docs/, ADRs, and exec-plans with file:line citations. Complements /fp-ask — use this when the question is "where did we write about X" rather than "interpret what we wrote". No AI required. Triggers on /fp-search <query>.
---

# fp-search

Find the file and line where something was written. Cheap, instant, deterministic — no interpretation.

## When to use /fp-search vs. /fp-ask

- `/fp-search <query>` — **where is it?** Returns ranked file:line hits with highlighted matches.
- `/fp-ask <question>` — **what does it mean?** Reads the relevant files, interprets, cites.

Reach for `/fp-search` when you just want to locate; reach for `/fp-ask` when you want a grounded answer.

## Process

1. Prefer the CLI:
   ```
   fastpace search "<query>" [--limit 20] [--context 2] [--case]
   ```
   If the CLI runs, use its output verbatim. It already ranks and highlights.
2. Fallback (if `fastpace` isn't on PATH or returns nothing): Grep the following roots in this order — context first, ADRs second, designs third:
   - `fastpace/context/*.md`
   - `fastpace/docs/adr/*.md`
   - `fastpace/docs/prd/*.md`, `fastpace/docs/erd/*.md`, `fastpace/docs/status-reports/*.md`
   - `fastpace/exec-plans/*.json`
   - `CLAUDE.md` (root) if no hits elsewhere
3. Return ranked results, max 10 by default, each with:
   - Relative path
   - Line number
   - ≤ 3 lines of surrounding context, with the query terms emphasized if you can

## Output format

```
fastpace/context/decisions.md:14  [context]
  │ ## 2025-02-14 — Postgres over DynamoDB
  │ **Context:** Multi-tenant transactional writes over JSON-heavy rows.
  │ DynamoDB's eventual consistency on secondary indices caused two audit bugs.

fastpace/docs/adr/0007-use-postgres-over-dynamo.md:1  [adr]
  │ # 0007. Use Postgres over DynamoDB
```

## Rules

- **No interpretation.** Return locations, not opinions. If the user asked "why", redirect to `/fp-ask`.
- **Cite file:line** for every hit. Never paraphrase without citing the exact source.
- **Respect noise.** Skip `node_modules/`, `dist/`, `build/`, `.git/`.
- **Don't grep the whole repo.** Only the fastpace-owned paths above.
- **Fall back gracefully.** If the query returns zero hits, suggest broader terms or `/fp-ask` for semantic lookup.

## Integration

- If hits are in `decisions.md` or ADRs, suggest the user open those — they're the most authoritative.
- If the user seems to want reasoning after seeing the hits, offer `/fp-ask` as a follow-up.
- `fastpace search` + `--limit` flag for power users.

## Exit criteria

- Ranked list printed, each hit with path:line + ≤ 3 context lines.
- Zero files modified.