whyspec-show

name	whyspec-show
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.

---

Input: A change name. If omitted, prompt for available changes.

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

   whyspec show --json "<name>"
   

   Parse the JSON response:

   • intent: Content of intent.md
   • design: Content of design.md
   • tasks: Content of tasks.md with completion status
   • context: Content of ctx_.md (if captured)
   • decision_bridge_delta: Computed delta of planned vs actual decisions
   • surprises: Decisions not in the original plan

   If no change name provided:

   • Run whyspec list --json to get available changes
   • Let the user select

2. Display the full story as a narrative arc

   # <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:

   ## Reasoning (AFTER)
   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:

   ## Decision Bridge

   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.
   ## Decision Bridge

   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.

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

No AskUserQuestion — this is a read-only display skill. If change name is missing, use whyspec list --json and let the user select.

Guardrails

• 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, 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.