why

Why

Investigate the motivation and intent behind code.

Companion to the how skill. how answers what the code does and how it works. why answers what forces led to its shape.

Spawn investigators with subagent_type: why-investigator and the synthesizer with subagent_type: why-synthesizer (Claude Code: Agent tool; OpenCode: task tool). Models come from those agent definitions; never pass model. Subagents cannot spawn subagents, so run this skill from the primary agent.

Operating Posture

Operate as a careful, cautious, and precise investigator. Be honest about what you know vs what you're inferring. Read references/epistemics.md for the full confidence framework and phrasing guide. The synthesizer must follow it.

Step 1. Understand the Target and the Question

Parse what the user is asking. The target is usually a chunk of code, a pattern, a feature, or a named design decision. The question is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep.

If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, selection, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.

Step 2. Establish the Code Anchor

Before spawning investigators, anchor the investigation in concrete code. You need:

• The relevant file path(s) and line range(s)
• The key symbols (function names, class names, constants)
• An initial commit list. The last few commits touching the target.
• PR numbers from merge commits (pattern (#1234) in the subject line)

Build this inline. If you cannot run shell commands (e.g. OpenCode conductor has bash denied), spawn one why-investigator for source control first to build the code anchor, then fan out.

# Blame target lines for last-touch commits
git blame -L <start>,<end> <file>

# Full file history, with patches, through renames
git log --follow -p -- <file>

# Last N commits touching the file, PR numbers visible
git log --oneline -20 -- <file>

# Extract PR numbers from a commit message
git log -1 --format=%B <commit>