Investigate motivation and design rationale behind code.

version
0.1.6
GitHub stars
347

Install

/plugin install why@khanelinix-ai-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add khaneliman/khanelinix.

Contents

Discovered from source

Skills 1

Why

Investigate the intent and constraints behind existing code. Identify why code took its current shape, what alternatives were rejected, and what edge cases or incidents forced specific defenses.

Companion to how (runtime behavior) and blast-radius (downstream impact).

Core Principles

  • Evidence before narrative: Collect citations first; do not fit evidence to an assumed story.
  • Cite everything: Reference commit hashes, PR numbers, tickets, docs, or code comments.
  • Hedge appropriately: Follow epistemics.md to separate direct facts from inference.
  • Document gaps: Null results across searched sources are meaningful data.

Workflow

1. Identify Target and Anchor Code

Parse user question and gather initial git context:

git blame -L <start>,<end> <file>
git log --follow -p -20 -- <file>
gh pr view <number> --json title,body,author,comments,reviews

Record file paths, line ranges, symbols, commit SHAs, and linked ticket numbers.

2. Follow Relevant Evidence

Start with sources likely to answer the question. A commit or linked design record may be sufficient. Use other tools only when they resolve a material gap or contradiction, or the user requests broader coverage. Tool availability alone does not justify a query.

For independent searches that benefit from delegation, use investigator-prompt.md. Keep simple investigations in the parent. Potential sources include:

  1. Source control: Commits, PR descriptions, review comments, tests (code-archaeology.md).
  2. Connected systems: Issue trackers, design documents, team chat, observability, error tracking, and product analytics, when the session has a tool for them. Use that tool's own search and filters.
  3. Defensive code: Consult incident-postmortem.md when investigating defensive checks.

Stop when the evidence sufficiently answers the question. Report the sources actually consulted and material limits; do not inventory or query unrelated systems to satisfy a coverage template.

3. Synthesize and Present

Answer a simple question directly with citations and any material uncertainty. For a complex investigation, use synthesizer-prompt.md to organize:

  • The Question: Concise restatement.
  • The Code: Anchoring files, symbols, and line ranges.
  • What We Found: Claims backed by direct citations.
  • Reasonable Inferences: Hedged conclusions from converging indirect evidence.
  • Competing Hypotheses: Alternative explanations if evidence is ambiguous.
  • What We Do Not Know: Unresolved questions and null search results.
  • Sources Consulted: Coverage map of all queried sources and gap justifications.

Sponsors

Details

Marketplace
khaneliman/khanelinix
Source
modules/common/ai-tools/skills/why
Author
khaneliman
Category
Developer Tools

More from khaneliman/khanelinix

All 43