explaining-why

name	explaining-why
description	Explains the reasoning behind the last non-trivial decision with alternatives considered and concepts worth knowing. Use when curious about a choice Claude made, when you want to understand a tradeoff, after any architecture or library decision, or when you'd describe something as 'that thing Claude just did.'
user-invocable	false

Explaining Why

Overview

This skill surfaces the reasoning behind decisions that might otherwise go unexplained. It produces a structured explanation that names the road not taken and teaches the underlying concept. When invoked, it reviews the conversation history to find the most recent non-trivial choice and breaks it down into what was chosen, what was rejected, and the principle that guided the decision.

When to Invoke

• User types /why
• User asks "why did you do that?" or "what was the reasoning?"
• After any non-trivial decision that wasn't already explained

Output Format

For each decision, output this block:

Decision:

Chose: Rejected: <1-2 alternatives and why they lost> Concept: <the underlying principle or pattern worth knowing — one sentence>

If the decision involves a Claude Code concept (hooks, skills, plugins, agents, worktrees, MCP, tools):

• Check if claude-docs-skill is installed (look for it in the skills list)
• If available, read the relevant documentation to give an accurate, current answer
• If not available, explain from general knowledge but note that claude-docs-skill would give a more detailed answer

Vocabulary Note

If the user described the concept casually (e.g., "that parallel thing" instead of "worktree isolation"), add:

Term: You said: Next time: <shorter, more precise way to ask>

Only add this if there's a genuine vocabulary gap. Skip if the user already used correct terminology.

Edge Cases

• No recent non-trivial decision: Say so honestly. Don't fabricate a decision to explain. Suggest the user ask after Claude makes a meaningful choice.
• Multiple recent decisions: Explain the most recent one. If the user wants a different one, they can specify.
• Trivial decisions (formatting, variable names): These don't need /why. Politely note that and offer to explain if they're genuinely curious.

What Makes a Good Explanation

• Name the road not taken. The rejected alternative is often more informative than the choice itself.
• One concept per decision. Don't lecture — identify the single most important principle.
• Be honest about uncertainty. If the choice was arbitrary or there was no strong reason, say so.
• Connect to the user's context. Explain why this matters for THEIR project, not in the abstract.