# Mine Why > Use when the user says: "why is this code like this", "why does this exist", "why was this built this way", "decision rationale", "what's the history behind". Decision archaeology — reconstructs historical rationale from evidence, not speculation. - Skill: `nodejsmith/mine-why` (Agent Skill) - Install (CLI): `npx skillmds@latest add nodejsmith/mine-why` - Raw SKILL.md: https://api.skillmd.com/api/skills/nodejsmith/mine-why/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: NodeJSmith (https://skillmd.com/u/nodejsmith) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/nodejsmith/mine-why --- # Why Decision archaeology for existing code. Reconstructs why code is shaped the way it is by querying multiple evidence sources in parallel. Operates under strict evidence-before-narrative epistemics — explicitly states when evidence is absent rather than speculating. Critical for safe refactoring: if you don't know why a constraint exists, removing it can break things that aren't obvious from the diff. ## How This Differs From Other Skills | Skill | What it answers | |-------|-----------------| | **`/mine-why`** | **"Why is this code shaped this way?"** — historical rationale | | `/mine-how` | "How does this work?" — runtime flow and mental models | | `/mine-research` | "What would it take to do X?" — forward-looking investigation | ## Arguments $ARGUMENTS — the code or decision to investigate. Can be: - A code pattern: `/mine-why "why does the dispatcher use a priority queue instead of FIFO?"` - A file: `/mine-why src/services/auth.py` - A constraint: `/mine-why "why is there a 30-second timeout on webhook retries?"` - A structural choice: `/mine-why "why are apps and services in separate directories?"` - Empty: ask the user what they want to understand ## Phase 1: Frame the Investigation If $ARGUMENTS is empty: ``` AskUserQuestion: question: "What code or decision do you want to understand the rationale behind?" header: "Investigate" multiSelect: false options: - label: "I'll type my question" description: "Ask about any code shape, constraint, or structural decision" - label: "Something in the current diff" description: "I'll point to specific code I'm about to change" ``` Identify the **target**: the specific code, file, pattern, or decision to investigate. If the user named a file, read it. If they named a pattern or constraint, grep to locate the relevant code. Record the target's file path(s) and line range(s). Run `get-skill-tmpdir mine-why` to establish ``. ## Phase 2: Gather Evidence Dispatch 6 parallel evidence-gathering agents. Each searches one category and writes findings to its own temp file. Null results are first-class evidence — "no issues found referencing this code" is a finding, not a failure. All agents use `subagent_type: "light-worker"`. ### Agent 1: Version Control History ``` Investigate the git history of this code to understand why it exists. Target: Question: Instructions: 1. Run git log on the target file(s): git log --follow --all -p -- 2. Run git blame on the specific lines: git blame -L , 3. For each significant commit, read the full commit message 4. Look for: the original commit that introduced this code, refactors that reshaped it, reverts that restored it, merge commits with context 5. Write findings to /evidence-git.md Format: - List each relevant commit: hash, date, author, full message, what changed - Note if the code has been stable (unchanged for months) or volatile (frequently modified) - Note if the introducing commit message explains the rationale - If git history is shallow or the file was moved, say so — don't guess ``` ### Agent 2: Issue Tracker and PRs ``` Search for issues and pull requests related to this code. Target: Question: Instructions: 1. Extract keywords from the target (function names, class names, feature terms) 2. Search issues: check `$ISSUE_TRACKER` (e.g., `printenv ISSUE_TRACKER`) for which tracker's tools to use, then search the project's issues for those keywords 3. Search PRs: run `git-platform` for which host's tools to use, then search that host's pull requests for the same keywords 4. For promising matches, read the body and first few comments 5. Write findings to /evidence-issues.md Steps 2 and 3 are independent — a project can file issues in one system while its PRs live on another, so `$ISSUE_TRACKER` says nothing about where the PRs are. Run both searches, and don't skip one because the other couldn't run. Format: - List each relevant issue/PR: number, title, key excerpt from body/comments - Note if an issue explicitly explains the design decision - If no issues or PRs reference this code, state that clearly - If a search couldn't run at all, write that fact as the finding for that search rather than folding it into an empty or ambiguous combined result. For example: "`$ISSUE_TRACKER` not configured, could not search issues" or "PR search failed: ". Report whatever the other search did find alongside it. This is the same null-result pattern as above. ``` ### Agent 3: Design Docs and Research ``` Search for design documents and research briefs related to this code. Target: Question: Instructions: 1. Glob for design docs: design/specs/*/design.md, design/research/*/research.md 2. Grep each for keywords related to the target 3. Also check: CLAUDE.md, README.md, ARCHITECTURE.md, docs/ directory 4. Read matching sections in full 5. Write findings to /evidence-design.md Format: - List each relevant doc: path, section heading, key excerpt - Note if a design doc explicitly chose this approach over alternatives - If no design docs reference this code, state that clearly ``` ### Agent 4: Rules, Comments, and Inline Rationale ``` Search for rules, comments, and inline explanations related to this code. Target: Question: Instructions: 1. Read the target code and all comments in/around it 2. Grep rules/ directory for keywords related to the target 3. Search for TODO, HACK, WORKAROUND, NOTE comments near the target 4. Check if any rules (rules/common/*.md) reference the pattern or constraint 5. Write findings to /evidence-rules.md Format: - List each relevant comment or rule: location, content - Note if a comment explains WHY (rationale) vs just WHAT (description) - If no comments or rules reference this code, state that clearly ``` ### Agent 5: Test Assertions as Constraints ``` Search for tests that encode constraints related to this code. Target: Question: Instructions: 1. Find test files that import or reference the target code 2. Read the test assertions — they often encode constraints that explain why code is shaped a certain way 3. Look for: parameterized tests with specific edge cases, regression tests with descriptive names, test comments explaining what they guard against 4. Write findings to /evidence-tests.md Format: - List each relevant test: file, test name, what it asserts, what constraint it implies - Note if a test name or comment references a bug number, incident, or specific scenario - If no tests reference this code, state that clearly ``` ### Agent 6: Conversation History ``` Search past Claude Code conversations for discussions relevant to this code. Target: Question: Instructions: 1. Run: ccrecall --json search-messages -q "" -n 8 2. Review each matched exchange for direct discussion of why this code is shaped this way — a decision being debated, a tradeoff being weighed, a bug being diagnosed, a constraint being explained out loud 3. For a promising match whose snippet is too short to judge on its own, run `ccrecall tail ` to read more surrounding context 4. Write findings to /evidence-conversations.md Format: - List each relevant exchange: session date, project, key excerpt, what it reveals about the rationale - Note whether the conversation explicitly settled the decision, versus just touching the topic in passing - If no relevant conversations are found, state that clearly — this history is often thin, or the decision predates the tracked conversation history ``` ## Phase 3: Synthesize After all evidence agents complete, dispatch a synthesis agent: ``` Agent(subagent_type: "standard-worker") ``` Synthesis prompt: ``` Synthesize evidence from six sources into a confidence-calibrated explanation of why code is shaped the way it is. Question: Target: Evidence files (read each in full): - /evidence-git.md - /evidence-issues.md - /evidence-design.md - /evidence-rules.md - /evidence-tests.md - /evidence-conversations.md Instructions: 1. Read all six evidence files 2. For each claim about rationale, assign a confidence level: - HIGH — multiple independent sources agree (e.g., commit message + design doc + test comment, or a conversation that explicitly settled it plus a matching commit) - MEDIUM — one source provides direct evidence (e.g., only a commit message, but it's clear) - LOW — evidence is indirect (e.g., a test implies a constraint but doesn't state it) - UNKNOWN — no evidence found; state this explicitly rather than speculating 3. Write the explanation to /synthesis.md Format: Start with a one-paragraph summary of the most likely rationale, stating the overall confidence level. Then for each aspect of the rationale: **[Aspect — e.g., "The priority queue was chosen over FIFO"]** Confidence: HIGH | MEDIUM | LOW | UNKNOWN Evidence: [cite specific sources — commit hash, issue number, doc path, test name] Explanation: [what the evidence says] End with: **Evidence gaps:** [what you looked for but didn't find — these are important for the reader to know. "No design doc covers this decision" is actionable information for someone considering a refactor.] Rules: - Never fill an UNKNOWN gap with speculation. "No evidence found" is the answer. - Treat null results as findings. "No issues reference this code" tells the reader that the decision predates the issue tracker or was never controversial. - If evidence conflicts (e.g., a commit message says one thing, a design doc says another), present both and flag the conflict rather than picking a winner. - Reference every claim with its source — commit hash, file:line, issue number. ``` ## Phase 4: Present Read `/synthesis.md` and present it conversationally in the main context. Do not write files or produce artifacts. If all aspects are UNKNOWN, say so directly: "I searched git history, issues, PRs, design docs, rules, comments, tests, and past conversations — none of them explain this decision. The rationale appears to be undocumented."