whyspec-search

name	whyspec-search
description	Use when looking for why something was built a certain way or finding past decisions.
argument-hint	<query> [--domain <domain>]

Search reasoning — find past decisions, contexts, and intent across all changes.

---

Input: A search query string. Optionally include --domain <domain> to filter by domain.

When to Search

Search is not just a lookup tool — it's the team knowledge check before new work:

• Before planning: "Has anyone reasoned about auth in this codebase before?"
• During debugging: "Have we seen this error pattern before? What was the root cause?"
• Before refactoring: "Why was this built this way? Was it a deliberate decision or tech debt?"
• During code review: "Does this approach contradict past decisions?"

Steps

1. Run the search

   whyspec search --json "<query>"
   

   If ARGUMENTS includes --domain:

   whyspec search --json "<query>" --domain "<domain>"
   

   Parse the JSON response — an array of scored results, each containing:

   • id: Context ID (e.g., ctx_a1b2c3d4) or file identifier
   • title: Context or intent title
   • change_name: Name of the change
   • domain: Auto-detected or specified domain
   • score: Relevance score (title=100, reasoning=30, files=20, general=10)
   • matched_sections: Which sections matched (title, reasoning, files, etc.)
   • path: File path for retrieval
   • snippet: Most relevant text excerpt

2. Display results with scores AND reasoning snippets

   ## Search: "authentication"

   Found 3 results:

   1. [score: 130] JWT Auth with RS256 (add-auth) Domain: authentication | Matched: title, reasoning

      "Chose RS256 over HS256 — allows key rotation without redeploying. Session stored in httpOnly cookie, not localStorage (XSS protection). Token expiry: 15min access, 7d refresh — balances security vs UX."

      This decision affects your current work if you're touching auth tokens or session management.

   2. [score: 30] Database Migration Plan (migrate-db) Domain: database | Matched: reasoning

      "Considered token storage in DB but rejected — added 3ms latency per request. Chose Redis for session cache instead (src/lib/redis.ts)."

   3. [score: 20] API Rate Limiting (add-rate-limits) Domain: api | Matched: files

      "src/middleware/auth.ts — modified to extract JWT sub claim for per-user rate limiting after authentication."

   View full story: /whyspec-show add-auth Narrow by domain: /whyspec-search "authentication" --domain auth Why good: Shows the actual reasoning from past decisions. A developer searching for "authentication" immediately sees WHY RS256 was chosen, WHY httpOnly cookies, and WHERE token decisions connect to rate limiting. The annotation "This decision affects..." connects past to present.

   ## Search: "authentication"

   Found 3 results:

   1. add-auth — JWT Authentication Setup
   2. migrate-db — Database Migration Plan
   3. add-rate-limits — API Rate Limiting

   Why bad: Just titles with no reasoning snippets. The developer has to open each one to find the relevant decision. Defeats the purpose of search.

   ## Search: "why is the session timeout 15 minutes"

   No results found for "why is the session timeout 15 minutes".

   Suggestions:

   • Try broader terms: "session", "timeout", "token expiry"
   • Search by domain: /whyspec-search "session" --domain auth
   • Check if this decision was captured: maybe it predates WhySpec adoption Why good: Empty results get helpful guidance, not a dead end.
   ## Search: "why is the session timeout 15 minutes"

   No results found. Why bad: Dead end. No help. User is stuck.

3. Connect results to the current context

   If the search was triggered during planning or debugging, connect the findings:

   • During /whyspec-plan: "Past decision in add-auth chose RS256 — your new feature should be compatible with this."
   • During /whyspec-debug: "Similar bug was investigated in debug-token-expiry — root cause was clock skew between services."
   • Standalone: Offer follow-up actions: /whyspec-show <name> or narrower search.

Tools

Tool	When to use	When NOT to use
Bash	Run whyspec search --json "<query>" — the primary search mechanism	Don't search manually with grep
Read	Follow up on results — read full context files when the snippet isn't enough	Don't read every result; focus on high-scoring ones
Grep	Supplement: search code for implementations referenced in search results	Don't use grep as a replacement for whyspec search

No AskUserQuestion — this is a display-only skill. Show results and offer follow-up commands.

Guardrails

• Always show scores — include the relevance score so the user understands ranking.
• Always show snippets — the reasoning excerpt is more useful than titles alone. Show the most relevant decision or trade-off text.
• Handle empty results helpfully — suggest broader terms, different keywords, or domain filters. Never just say "No results."
• Don't fabricate results — only display what the CLI returns. Never synthesize or guess at matches.
• Connect past to present — when results are clearly relevant to ongoing work, say so explicitly.
• Search includes plan files — the CLI searches intent.md and design.md too, not just context files. This finds planned decisions that haven't been captured yet.