@gitwhy-cli/whyspec 0.1.17 → 0.1.19

package/skill-sources/whyspec-execute/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: whyspec-execute
+description: Use when starting implementation, continuing work, or executing tasks from a WhySpec plan.
+argument-hint: "[change-name]"
+---
+
+Implement a change — read the plan, work through tasks, commit atomically.
+
+When all tasks are done, run `/whyspec:capture` to save your reasoning.
+
+---
+
+**Input**: Optionally specify a change name. If omitted, auto-detect or prompt for available changes.
+
+## Iron Law
+
+**NEVER SKIP THE PLAN.** Read intent.md and design.md before writing a single line of code. The plan is the contract — if reality doesn't match the plan, update the plan first.
+
+## Red Flags — If You're Thinking This, STOP
+
+- "The plan is clear enough, I'll just start coding" → Read intent.md. Now. It takes 15 seconds.
+- "I'll batch all changes into one commit at the end" → One commit per task. That's the contract.
+- "This task seems unnecessary, I'll skip it" → Ask the user to remove it. Don't silently skip.
+- "The design says X but Y is clearly better" → Flag the contradiction. Don't silently override.
+- "I'm done, no need to run the verify step" → Run it. Evidence beats confidence.
+
+## Steps
+
+1. **Select the change**
+
+   If ARGUMENTS provides a name, use it. Otherwise:
+   - Auto-select if only one active change exists
+   - If multiple changes exist, run `whyspec list --json` and let the user select
+
+   Announce: "Executing change: **<name>**"
+
+2. **Load execution context**
+
+   ```bash
+   whyspec execute --json "<name>"
+   ```
+
+   Parse the JSON response:
+   - `change_name`: The change being executed
+   - `intent`: Content of intent.md
+   - `design`: Content of design.md
+   - `tasks`: Content of tasks.md
+   - `progress`: `{ total, completed, remaining }`
+   - `pending_tasks`: Array of uncompleted tasks
+
+3. **Read plan files for context**
+
+   Read the full content of:
+   - `intent.md` — understand WHY this change exists, what constraints apply
+   - `design.md` — understand HOW to approach it, what decisions are pending
+   - `tasks.md` — understand WHAT to implement and how to verify
+
+   Keep intent and design in mind throughout implementation. When making a decision during coding, check if it's listed under "Decisions to Make" — you're resolving the Decision Bridge in real-time.
+
+4. **Show current progress**
+
+   ```
+   ## Executing: <name>
+
+   Progress: N/M tasks complete
+   Remaining:
+   - [ ] Task description 1
+   - [ ] Task description 2
+   ```
+
+5. **Implement tasks sequentially**
+
+   For each pending task:
+
+   a. Show: `Working on task N/M: <description>`
+   b. Implement the code changes
+   c. Mark task complete in tasks.md: `- [ ]` → `- [x]`
+   d. Run the task's `verify:` check if one is defined
+   e. Commit atomically — one commit per task or logical unit
+   f. Continue to next task
+
+   <examples>
+   <good>
+   Working on task 3/5: Add rate-limit middleware
+
+   Reading src/middleware/index.ts — current chain: cors → helmet → bodyParser → routes
+   Installing express-rate-limit@7.1.0 (compatible with Express 4.18)
+   Added rateLimiter middleware after helmet at src/middleware/index.ts:14
+   Config: 100 req/15min window, Redis store via existing src/lib/redis.ts client
+
+   verify: `npm test -- --grep "rate-limit"` → 4 tests pass
+   verify: `curl -I localhost:3000/api/users` → X-RateLimit-Limit: 100 header present
+
+   Committed: "feat(middleware): add rate-limit middleware with Redis backing"
+   Why good: References exact files/lines, shows what was done and why,
+   runs specific verification commands, commits atomically with clear message.
+   </good>
+
+   <bad>
+   Working on task 3/5: Add rate-limit middleware
+   Done! Moving to task 4.
+   Why bad: No detail about what was implemented. No verification.
+   No commit. The user can't tell if this was done correctly.
+   </bad>
+
+   <good>
+   Working on task 2/4: Refactor auth to use JWT
+   PAUSE — design.md says "cookie-based sessions" (design.md:12) but this task
+   says "JWT". This contradicts the design.
+   Options:
+   A) Update design.md to JWT and continue (Recommended — JWT aligns with the API-first intent)
+   B) Implement cookie-based sessions as designed
+   C) Discuss the trade-offs before deciding
+   Why good: Catches a contradiction between plan and task. Stops to resolve
+   with specific options instead of silently making a decision.
+   </good>
+
+   <bad>
+   Working on task 2/4: Refactor auth to use JWT
+   Design says cookies but I'll use JWT since the task says so.
+   Why bad: Silently overrides the design without flagging the contradiction.
+   </bad>
+   </examples>
+
+6. **On completion**
+
+   Report status using completion codes:
+
+   | Status | When | What to show |
+   |--------|------|-------------|
+   | DONE | All tasks completed and verified | Full summary + `/whyspec:capture` prompt |
+   | DONE_WITH_CONCERNS | Tasks done but something feels off | Summary + concerns + `/whyspec:capture` |
+   | BLOCKED | Cannot proceed without input | Blocker details + resume command |
+   | NEEDS_CONTEXT | Missing information | Specific question about what's missing |
+
+   ```
+   ## DONE
+
+   Change: <name>
+   Progress: M/M tasks complete
+
+   Completed:
+   - [x] Task 1: description — committed as "feat: ..."
+   - [x] Task 2: description — committed as "feat: ..."
+
+   Ready to capture reasoning? Run /whyspec:capture
+   ```
+
+## Tools
+
+| Tool | When to use | When NOT to use |
+|------|------------|-----------------|
+| **Read** | Read plan files (intent.md, design.md, tasks.md) BEFORE coding | Don't skip reading the plan |
+| **Grep** | Find affected code before editing (e.g., all usages of a function you're changing) | Don't grep after editing — grep BEFORE to understand impact |
+| **Edit** | Modify existing files — prefer Edit over Write for existing code | Don't rewrite entire files when a targeted edit suffices |
+| **Write** | Create new files only | Don't use Write to modify existing files |
+| **Bash** | Run tests (`npm test`), verify (`curl`, build commands), commit (`git commit`) | Don't run destructive git commands without asking |
+| **AskUserQuestion** | When a task is unclear, or design contradicts implementation (see format below) | Don't ask about things you can determine from the plan or code |
+
+### AskUserQuestion Format (use for contradictions and blockers)
+
+1. **Re-ground**: "Executing task N/M of **<change>** — `<task description>`"
+2. **The contradiction/blocker**: What you found vs what the plan says
+3. **Options with recommendation**: Lettered choices with your pick
+
+<examples>
+<good>
+Executing task 2/4 of **add-rate-limiting** — "Configure Redis store"
+
+design.md says use the existing ioredis client (src/lib/redis.ts:8), but that
+client uses `db: 0` which is shared with session data. Rate limit keys could
+collide with session keys.
+
+A) Use db: 0 with a `ratelimit:` key prefix (simple, small collision risk)
+B) Create a separate client on db: 1 (isolated, adds ~2MB memory)
+C) Reuse db: 0 but with a Redis namespace library
+
+I'd recommend B — isolation is worth 2MB.
+Why good: Specific blocker with evidence from code. Options with trade-offs.
+</good>
+</examples>
+
+## Escalation Protocol
+
+| Situation | Attempts allowed | Action |
+|-----------|-----------------|--------|
+| Task is unclear or ambiguous | 0 — ask immediately | Ask ONE specific clarification question |
+| Implementation keeps failing | 3 attempts max | Report: what was tried, what failed, what error |
+| Design contradiction found | 0 — flag immediately | Present options, let user decide |
+| Unexpected dependency or constraint | 1 attempt to resolve | If can't resolve, present findings and ask |
+
+## Rationalization Table
+
+| If you catch yourself thinking... | Reality |
+|----------------------------------|---------|
+| "I'll read the plan later, the task name is clear enough" | The plan has constraints you'll violate. Read it. 15 seconds. |
+| "One big commit is fine, I'll split it later" | You won't. Atomic commits are the contract. Do it now. |
+| "This test is probably passing, no need to run it" | "Probably" is not evidence. Run the test. |
+| "I'll skip the verify step for this trivial task" | Trivial tasks have trivial verifications. Run them anyway. |
+| "The design is slightly wrong but my way is better" | Flag it. The user made the design for a reason you might not see. |
+
+## Guardrails
+
+- **Read intent.md before coding** — every implementation decision should align with the stated intent and constraints.
+- **Never skip tasks** — work through all tasks in order. If a task seems unnecessary, ask the user to remove it rather than silently skipping.
+- **Commit atomically** — one commit per task or logical unit. Don't batch all changes into one commit.
+- **Pause on unclear tasks** — don't guess at ambiguous requirements. Ask for clarification.
+- **Pause on design issues** — if reality doesn't match the plan, stop and suggest design.md updates before continuing.
+- **Mark checkboxes immediately** — update tasks.md after each task completion, not at the end.
+- **Always prompt capture** — end every execution session with the `/whyspec:capture` suggestion.

package/skill-sources/whyspec-plan/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: whyspec-plan
+description: Use when planning a code change, capturing decisions before coding, or setting up the Decision Bridge.
+argument-hint: "<change-name-or-description>"
+---
+
+Plan a change — create intent.md, design.md, and tasks.md with the Decision Bridge.
+
+When ready to implement, run `/whyspec:execute`
+
+---
+
+**Input**: A change name (kebab-case) or description of what to build via ARGUMENTS.
+
+## Iron Law
+
+**ACT FIRST, ASK ONLY WHEN STUCK.** The user invoked `/whyspec:plan` with a description of what they want. Your job is to structure their intent into plan files — not to interview them.
+
+## Red Flags — If You're Thinking This, STOP
+
+- "I should ask what problem this solves" → The user TOLD you. Read ARGUMENTS.
+- "Let me ask about constraints first" → Explore the codebase. Find them yourself.
+- "I need more context before I can plan" → You have a codebase. Read it.
+- "This is too vague to plan" → Even "fix auth" is enough. Read the auth code, find the issues, plan the fix.
+- "I'll create a generic template and ask the user to fill it in" → That's not planning. That's homework assignment.
+
+## Steps
+
+1. **Parse ARGUMENTS and infer intent**
+
+   Read what the user typed. Derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **If ARGUMENTS is empty or a single ambiguous word** (e.g., just "plan" or "help"):
+   Ask ONE question: "What change are you planning?" — then proceed.
+
+   **If ARGUMENTS has any meaningful description** (even brief):
+   Proceed immediately. Do NOT ask forcing questions. The user told you what they want.
+
+   <examples>
+   <good>
+   User: `/whyspec:plan add dark mode support`
+   Agent: Creates change folder, writes intent.md capturing dark mode as the goal,
+   design.md with CSS custom properties vs class-based approach trade-off,
+   tasks.md with implementation steps.
+   Why good: User stated what they want. Agent structured it into plan files without interrogation.
+   </good>
+
+   <bad>
+   User: `/whyspec:plan add dark mode support`
+   Agent: "What problem does this solve? Who feels this pain today?"
+   Why bad: The user literally just told you — they want dark mode. Asking "what problem does
+   this solve" is patronizing checklist-walking. The answer is obvious from the input.
+   </bad>
+
+   <good>
+   User: `/whyspec:plan`
+   Agent: "What change are you planning?"
+   Why good: ARGUMENTS is empty. ONE question to get started is justified.
+   </good>
+
+   <bad>
+   User: `/whyspec:plan refactor auth middleware`
+   Agent: "What constraints exist? What does success look like? How will you know it works?"
+   Why bad: Three rounds of corporate interview questions. The user wants to refactor auth
+   middleware — explore the codebase to understand constraints, don't ask generic questions.
+   </bad>
+   </examples>
+
+2. **Create the change folder**
+
+   ```bash
+   whyspec plan --json "<name>"
+   ```
+
+   Parse the JSON response:
+   - `path`: The change directory (e.g., `.gitwhy/changes/add-auth/`)
+   - `templates`: Template content for intent.md, design.md, tasks.md
+   - `context`: Project context from config.yaml (constraints for you — do NOT copy into files)
+   - `rules`: Project-specific rules (constraints for you — do NOT copy into files)
+
+   If a change with that name already exists, ask: continue the existing change, or create a new one with a different name?
+
+3. **Explore codebase for context** (if the change touches existing code)
+
+   Before writing plan files, read relevant code to understand:
+   - Current architecture in the affected area
+   - Existing patterns and conventions
+   - Dependencies and constraints
+
+   <examples>
+   <good>
+   User wants to add rate limiting.
+   Agent reads src/middleware/index.ts, finds Express + helmet at line 12,
+   sees the middleware chain: cors → helmet → bodyParser → routes.
+   Writes design.md: "Insert express-rate-limit after helmet in the existing
+   chain at src/middleware/index.ts:14. Use sliding window algorithm.
+   Redis backing via existing ioredis client at src/lib/redis.ts."
+   Why good: References exact files, line numbers, existing dependencies.
+   Plan is grounded in code the agent actually read.
+   </good>
+
+   <bad>
+   User wants to add rate limiting.
+   Agent writes design.md: "Consider using express-rate-limit or a custom
+   middleware solution. Evaluate Redis vs in-memory storage."
+   Why bad: Generic advice from training data. Ignores the actual codebase.
+   Could have been written without reading a single file.
+   </bad>
+   </examples>
+
+4. **Create intent.md**
+
+   Write to `<path>/intent.md`. Here's a concrete filled-in example:
+
+   ```markdown
+   ## Why This Change Exists
+
+   POST /api/users returns 500 under load because we have no rate limiting.
+   Production logs show 12k requests/min from a single IP during the March 28 incident.
+
+   ## What It Enables
+
+   API stability under load. Prevents abuse without blocking legitimate traffic.
+
+   ## Decisions to Make
+
+   - [ ] Rate limit storage: Redis (shared across 3 instances) vs in-memory (simpler, single-instance only)?
+   - [ ] Limit granularity: per-IP vs per-user-token vs both?
+   - [ ] Response on limit: 429 with Retry-After header vs 429 with custom error body?
+
+   These checkboxes form the "before" side of the Decision Bridge.
+   They will be resolved during /whyspec:capture after implementation.
+
+   ## Constraints
+
+   - Must work with existing Express middleware chain (cors → helmet → bodyParser → routes)
+   - Redis (ioredis) already available at src/lib/redis.ts — prefer reuse over new dependency
+   - P99 latency budget: <5ms per request for rate limit check
+
+   ## Success Looks Like
+
+   - `npm test` passes with rate limit integration tests
+   - Siege test: 1000 req/s returns 429 after threshold, Retry-After header present
+   - No latency regression visible in existing API benchmark
+
+   ## Assumptions
+
+   - Redis is available in all environments (need to verify staging)
+   - Current ioredis client supports the rate limiting pattern we choose
+   ```
+
+   **IMPORTANT**: The "Decisions to Make" checkboxes are the Decision Bridge. Every unsettled design choice MUST be listed here.
+
+   <examples>
+   <good>
+   ## Decisions to Make
+   - [ ] Rate limit storage: Redis (shared across instances) vs in-memory (simpler, single-instance only)?
+   - [ ] Limit granularity: per-IP vs per-user-token vs both?
+   - [ ] Response on limit: 429 with Retry-After header vs 429 with custom error body?
+   Why good: Specific, actionable decisions with concrete options derived from the codebase.
+   </good>
+
+   <bad>
+   ## Decisions to Make
+   - [ ] What technology to use?
+   - [ ] How to implement it?
+   - [ ] What approach is best?
+   Why bad: Vague decisions that could apply to literally any change. Not useful.
+   </bad>
+   </examples>
+
+5. **Create design.md**
+
+   Write to `<path>/design.md`. Skip the trade-off matrix for simple changes:
+
+   ```markdown
+   ## Approach
+
+   [Chosen technical direction — 2-3 sentences grounded in the actual codebase]
+
+   ## Trade-off Matrix
+
+   | Option | [Criterion 1] | [Criterion 2] | [Criterion 3] |
+   |--------|---------------|---------------|---------------|
+   | Option A | ... | ... | ... |
+   | Option B | ... | ... | ... |
+
+   ## Architecture
+
+   [ASCII diagram showing the design — components, data flow, boundaries]
+
+   ## Questions to Resolve
+
+   - [ ] [Open question needing an answer before or during coding]
+
+   ## Risks & Unknowns
+
+   - [What could go wrong]
+
+   ## Dependencies
+
+   - [External libraries, APIs, services]
+   ```
+
+6. **Create tasks.md**
+
+   Write to `<path>/tasks.md`. Define verification FIRST — goal-backward planning:
+
+   ```markdown
+   ## Verification
+
+   What proves this change works — defined BEFORE tasks:
+
+   - [ ] [Verification criterion 1]
+   - [ ] [Verification criterion 2]
+
+   ## Tasks
+
+   - [ ] Task 1: [description]
+     verify: [how to verify this specific task]
+   - [ ] Task 2: [description]
+     verify: [verification step]
+   ```
+
+   Each task should be small enough for one atomic commit.
+
+7. **Show summary**
+
+   ```
+   ## Plan Created: <name>
+
+   <path>/
+     intent.md    — WHY: problem, constraints, success criteria
+     design.md    — HOW: approach, trade-offs, decisions to make
+     tasks.md     — WHAT: verification criteria + implementation checklist
+
+   Decisions to make: N pending
+   Tasks: N defined
+
+   Ready to implement? Run /whyspec:execute
+   ```
+
+## Tools
+
+| Tool | When to use | When NOT to use |
+|------|------------|-----------------|
+| **Glob** | Find files by pattern before writing plan (e.g., `src/middleware/**/*.ts`) | Don't glob blindly — know what area you're looking for |
+| **Grep** | Search for patterns in code (e.g., existing rate limit logic, auth middleware) | Don't grep the whole repo — scope to relevant dirs |
+| **Read** | Read specific files to understand architecture before planning | Don't read files unrelated to the change |
+| **Bash** | Run `whyspec plan --json` (CLI-as-oracle). Run `git log` to understand recent changes | Don't run destructive commands |
+| **AskUserQuestion** | ONLY when ARGUMENTS is empty or genuinely ambiguous (see format below) | Don't ask questions answerable by reading code |
+
+### Codebase First, Web Never-First
+
+Read the codebase BEFORE considering web search. Web search is justified ONLY when:
+- The change involves a library/framework not present in the codebase
+- You need version-specific migration docs
+- Security advisory lookup (CVEs)
+
+Never search the web for: architecture decisions, "best practices", or how to use a library already in the codebase.
+
+### AskUserQuestion Format (use sparingly)
+
+When you MUST ask (ARGUMENTS empty, or genuinely stuck after codebase exploration):
+
+1. **Re-ground**: "Planning **<change>** in `<project>` on `<branch>`"
+2. **What you found**: Show what you already discovered in the codebase
+3. **One specific question**: Not a checklist. One thing you need.
+4. **Recommendation**: "I'd suggest X because Y — your call"
+
+<examples>
+<good>
+Planning **add-rate-limiting** in `my-api` on `main`
+
+I found Express 4.18 with helmet middleware at src/middleware/index.ts,
+and an existing ioredis client at src/lib/redis.ts.
+
+Should the rate limit apply globally (all routes) or only to /api/* routes?
+I'd suggest /api/* only — internal health checks shouldn't be rate-limited.
+Why good: Shows what was already found. Asks ONE specific question with a recommendation.
+</good>
+
+<bad>
+What problem does this solve? What constraints exist? How will you know it works?
+Why bad: Three generic questions. No codebase context. Classic checklist-walking.
+</bad>
+</examples>
+
+## Escalation Protocol
+
+If you hit any of these, STOP and ask the user (max 3 attempts before escalating):
+
+| Situation | Action |
+|-----------|--------|
+| ARGUMENTS is genuinely ambiguous after codebase exploration | Ask ONE specific question, not a checklist |
+| Multiple valid architectures with no clear winner | Present the trade-off matrix, ask user to pick |
+| Change requires access or knowledge you don't have | State what you know, what you need, and ask |
+| After 3 failed attempts to infer intent | Escalate: "I need more context. Here's what I've found so far: [findings]" |
+
+## Guardrails
+
+- **Don't interrogate the user** — if ARGUMENTS contains a meaningful description, proceed. Only ask when ARGUMENTS is empty or genuinely ambiguous.
+- **Ground plans in the codebase** — read relevant code before writing. Plans that ignore the actual architecture are useless.
+- **Don't implement code** — this skill creates plan files only. Implementation happens in `/whyspec:execute`.
+- **Don't skip "Decisions to Make"** — every unsettled design choice must be a checkbox. If you can't find any decisions, you haven't thought hard enough about the change.
+- **Use CLI-as-oracle** — always call `whyspec plan --json` to create the folder. Don't create paths or generate IDs manually.
+- **Apply `context` and `rules` as constraints** — they guide your writing but must NOT appear in the output files.
+- **Verification before tasks** — in tasks.md, define what "done" looks like before listing the work.
+- **Scale to the change** — a typo fix gets a 3-line intent and 1 task. A major refactor gets the full treatment.
+
+## Rationalization Table
+
+| If you catch yourself thinking... | Reality |
+|----------------------------------|---------|
+| "I should ask the user some clarifying questions first" | Read the codebase. Most "clarifying questions" can be answered by reading code. |
+| "The user's description is too vague to plan" | Even "fix auth" is plannable — read the auth code, find the issues, plan the fix. |
+| "I need to understand the full architecture before planning" | Plan the change, not the universe. Read what's relevant, skip what's not. |
+| "I should create a comprehensive plan with all sections" | Scale to the change. A 1-line fix gets a 3-line plan. Don't over-engineer. |
+| "Let me ask about success criteria" | Infer from the change. "Success = tests pass + the thing works." Write it yourself. |
+| "I'll write generic placeholder text and the user can fill it in" | That's not planning. Populate every field with specific, codebase-grounded content. |
+
+## Anti-Patterns
+
+| If you're about to... | STOP — do this instead |
+|----------------------|----------------------|
+| Ask "What problem does this solve?" | Read ARGUMENTS — the user just told you |
+| Ask "What constraints exist?" | Explore the codebase — find the constraints yourself |
+| Ask "Who is this for?" | This is a code change, not a product pitch |
+| Write a generic plan without reading code | Read the affected files first |
+| Create a massive plan for a small fix | Scale the plan to match the change size |
+| Skip Decisions to Make because "it's obvious" | If it's obvious, write it down — it takes 10 seconds |

package/skill-sources/whyspec-search/SKILL.md

@@ -0,0 +1,137 @@
+---
+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**
+
+   ```bash
+   whyspec search --json "<query>"
+   ```
+
+   If ARGUMENTS includes `--domain`:
+   ```bash
+   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**
+
+   <examples>
+   <good>
+   ## 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.
+   </good>
+
+   <bad>
+   ## 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.
+   </bad>
+
+   <good>
+   ## 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.
+   </good>
+
+   <bad>
+   ## Search: "why is the session timeout 15 minutes"
+
+   No results found.
+   Why bad: Dead end. No help. User is stuck.
+   </bad>
+   </examples>
+
+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.