@gitwhy-cli/whyspec 0.1.16 → 0.1.18

package/skills/whyspec-search/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: whyspec-search
-description: Search past reasoning, decisions, and contexts across all changes. Use when looking for why something was built a certain way, finding past decisions, or discovering institutional knowledge.
+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.
@@ -9,7 +10,16 @@ Search reasoning — find past decisions, contexts, and intent across all change
 
 **Input**: A search query string. Optionally include `--domain <domain>` to filter by domain.
 
-**Steps**
+## 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**
 
@@ -17,7 +27,7 @@ Search reasoning — find past decisions, contexts, and intent across all change
    whyspec search --json "<query>"
    ```
 
-   If a domain filter is specified:
+   If ARGUMENTS includes `--domain`:
    ```bash
    whyspec search --json "<query>" --domain "<domain>"
    ```
@@ -32,38 +42,96 @@ Search reasoning — find past decisions, contexts, and intent across all change
    - `path`: File path for retrieval
    - `snippet`: Most relevant text excerpt
 
-2. **Display results with scores and snippets**
+2. **Display results with scores AND reasoning snippets**
 
-   ```
-   ## Search: "<query>"
+   <examples>
+   <good>
+   ## Search: "authentication"
 
-   Found N results:
+   Found 3 results:
 
-   1. [score: 130] **JWT Authentication Setup** (add-auth)
+   1. [score: 130] **JWT Auth with RS256** (add-auth)
       Domain: authentication | Matched: title, reasoning
-      > "Chose RS256 over HS256 — allows key rotation without redeploying"
+      > "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 — latency concerns"
+      > "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/auth/middleware.ts — modified"
-   ```
+      > "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.
 
-   For each result, show the most relevant decision or reasoning snippet — not just the title.
+## Tools
 
-3. **Offer follow-up actions**
+| 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 |
 
-   After displaying results:
-   - "View full story: `/whyspec-show <change-name>`"
-   - "Narrow by domain: `/whyspec-search \"<query>\" --domain <domain>`"
+No AskUserQuestion — this is a display-only skill. Show results and offer follow-up commands.
 
-**Guardrails**
+## Guardrails
 
-- **Always show scores** — include the relevance score so the user understands why results are ranked.
+- **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 clearly** — if nothing matches, say "No results found for '<query>'" and suggest broader search terms or different keywords.
+- **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.

package/skills/whyspec-show/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: whyspec-show
-description: Display the full story of a change — intent, design, tasks, and reasoning — with the Decision Bridge delta showing how decisions evolved from plan to implementation.
+description: Use when reviewing the full story of a change — intent, design, tasks, and Decision Bridge delta.
+argument-hint: "[change-name]"
 ---
 
 Show the full story — from intent through design, tasks, and reasoning — with the Decision Bridge delta.
@@ -9,7 +10,18 @@ Show the full story — from intent through design, tasks, and reasoning — wit
 
 **Input**: A change name. If omitted, prompt for available changes.
 
-**Steps**
+## What Makes a Good Story
+
+The show command doesn't just dump files — it tells the **narrative arc** of a change:
+1. **Intent** — Why did we start this? What pain existed?
+2. **Design** — How did we plan to solve it? What trade-offs did we consider?
+3. **Tasks** — What concrete work was done? How much is complete?
+4. **Reasoning** — What actually happened? What surprised us?
+5. **Decision Bridge** — How did our thinking evolve from plan to reality?
+
+The Decision Bridge delta is the most valuable output — it reveals the gap between what we THOUGHT we'd do and what we ACTUALLY did.
+
+## Steps
 
 1. **Get the full story from CLI**
 
@@ -27,7 +39,7 @@ Show the full story — from intent through design, tasks, and reasoning — wit
 
    If no change name provided:
    - Run `whyspec list --json` to get available changes
-   - Use **AskUserQuestion** to let the user select
+   - Let the user select
 
 2. **Display the full story as a narrative arc**
 
@@ -35,56 +47,94 @@ Show the full story — from intent through design, tasks, and reasoning — wit
    # <Change Name>
 
    ## Intent (WHY)
-
    [From intent.md — problem statement, what it enables, constraints, success criteria]
 
    ## Design (HOW)
-
    [From design.md — approach, architecture, trade-offs considered]
 
    ## Tasks (WHAT)
-
    [From tasks.md — task list with completion status]
    Progress: N/M tasks complete
 
    ## Reasoning (AFTER)
-
    [From ctx_<id>.md — story of what happened, decisions made, trade-offs accepted]
    ```
 
-   If context hasn't been captured yet, show:
+   If context hasn't been captured yet:
    ```
    ## Reasoning (AFTER)
-
-   Not yet captured. Run /whyspec-capture to complete the story.
+   Not yet captured. Run /whyspec:capture to complete the story.
    ```
 
 3. **Highlight the Decision Bridge Delta**
 
    When both plan files and context exist, display the evolution:
 
-   ```
+   <examples>
+   <good>
    ## Decision Bridge
 
-   | Decision | Planned (Before) | Actual (After) | Status |
-   |----------|-------------------|----------------|--------|
-   | Token storage | cookie vs localStorage? | httpOnly cookie — XSS protection | Resolved |
-   | Hashing algorithm | bcrypt vs argon2? | bcrypt — better library support | Resolved |
-   | Session strategy | JWT vs server-side? | JWT — no session store needed | Resolved |
-   | [Unresolved item] | X vs Y? | — | Pending |
+   | Decision | Planned (Before) | Actual (After) | Delta |
+   |----------|-------------------|----------------|-------|
+   | Rate limit storage | Redis vs in-memory? | Redis — 3 instances need shared state | As planned |
+   | Limit granularity | per-IP vs per-token? | Both — IP for anon, token for auth'd | Expanded scope |
+   | 429 response | standard vs custom? | Standard + Retry-After header | As planned |
 
    ### Surprises (not in original plan)
+   - **Added X-Request-ID middleware** — needed for debugging 429 responses.
+     Impact: New dependency on uuid package, new middleware in chain.
+   - **Changed Redis key schema to sorted sets** — sliding window algorithm
+     requires sorted sets, not simple strings. Affects memory profile.
+
+   ### Delta Summary
+   - 3 planned decisions: 2 as planned, 1 expanded scope
+   - 2 surprises: both additive (no plan contradictions)
+   - Design alignment: HIGH — implementation closely followed the plan
+   Why good: Every decision shows BEFORE (question) and AFTER (answer + rationale).
+   Surprises are documented with impact. Delta summary gives the big picture.
+   The "Expanded scope" and "As planned" labels make evolution visible at a glance.
+   </good>
+
+   <bad>
+   ## Decision Bridge
 
-   - Added 2FA — security review required it
-   - Added rate limiting on login — discovered during load testing
-   ```
+   | Decision | Status |
+   |----------|--------|
+   | Storage | Done |
+   | Limit scope | Done |
+   | 429 response | Done |
+   Why bad: No before/after comparison. "Done" tells you nothing about what
+   was decided or why. The entire point of the Decision Bridge is showing
+   how thinking evolved.
+   </bad>
+   </examples>
+
+4. **Handle partial stories gracefully**
+
+   Not every change has all files. Show what exists and guide the user:
+
+   | Missing | What to show | Suggestion |
+   |---------|-------------|------------|
+   | No design.md | Intent + Tasks only | "Design not captured. Was this a quick fix?" |
+   | No tasks.md | Intent + Design only | "No tasks defined. Run `/whyspec:execute` to start." |
+   | No context | Intent + Design + Tasks | "Reasoning not captured yet. Run `/whyspec:capture`." |
+   | No intent (shouldn't happen) | Whatever exists | "Intent missing — this change may not have been planned with WhySpec." |
+   | Tasks partially done | Show progress bar | "Progress: ███░░ 3/5 tasks — resume with `/whyspec:execute <name>`" |
+
+## Tools
+
+| Tool | When to use | When NOT to use |
+|------|------------|-----------------|
+| **Bash** | Run `whyspec show --json "<name>"` and `whyspec list --json` | Don't modify anything — this is read-only |
+| **Read** | Read raw files if CLI output is insufficient or truncated | Don't read files the CLI already provided |
 
-   The delta is the most valuable output of `/whyspec-show` — it reveals how thinking evolved from plan to reality.
+No AskUserQuestion — this is a read-only display skill. If change name is missing, use `whyspec list --json` and let the user select.
 
-**Guardrails**
+## Guardrails
 
-- **Show all available phases** — always display intent, design, tasks, and context (if present). Don't skip sections even if they're short.
-- **Always show the Decision Bridge delta** — when both plan and context exist, the delta table is mandatory. It's the core differentiator.
-- **Handle missing files gracefully** — if some files don't exist, show what's available and note what's missing. Suggest the appropriate command to fill gaps.
+- **Show all available phases** — always display intent, design, tasks, and context (if present). Don't skip sections.
+- **Always show the Decision Bridge delta** — when both plan and context exist, the delta table is mandatory.
+- **Handle missing files gracefully** — show what's available, note what's missing, suggest the command to fill gaps.
 - **Read-only** — this skill displays information. It never modifies files.
-- **Show completion status** — for tasks, always show N/M complete. For the Decision Bridge, show how many decisions were resolved vs pending.
+- **Show completion status** — for tasks, show N/M complete. For the Decision Bridge, show resolved vs pending counts.
+- **Tell the story, don't dump data** — organize output as a narrative arc, not a raw file concatenation.