SkillRepo
Sign InSign Up
Catalog
Yeachan-Heo/why

Yeachan-Heo

why

Investigate why code is the way it is from evidence — human rulings verbatim, git archaeology, linked issues, incident records — every claim labeled evidence, inference, or guess. For 'why was this built this way'.

v1.0LATEST
NewUpdated Nov 8, 2026

Why

Answer "why is it like this?" from evidence, not vibes. The deliverable is a cited answer, not a fix; a fix that falls out of the answer goes through its own lane.

When to use

  • "why was this built this way", "why does this exist"
  • "are we sure about Z" before betting work on Z
  • "should we do X or Y" where the answer lives in history, not preference

Sources, in order of authority

  1. Human rulings. A decision a person made is quoted verbatim with attribution (commit message, issue comment, PR review, chat log). Never paraphrase a ruling into your own words; label agent interpretations as interpretations, and missing originals as missing. A copy of a ruling is not a new decision.
  2. Code archaeology. git log --follow, git log -S, blame on the deciding lines, and the diff that introduced them. Name the commit and what problem its message claims to solve.
  3. Linked records. Issues and PRs reachable from the code (references in commit messages, gh issue list --state all --search, PR review threads) — acceptance criteria and rejected alternatives live here.
  4. Incident and observability sources. When configured, query them through their own tools (Sentry, Datadog, Databricks, dashboards, incident postmortems) or MCP servers (Slack, Linear, Notion). Cite the alert, thread, ticket, or postmortem. If a source needs credentials you do not have, say so and move on.

Method

  1. State the question and what would count as an answer.
  2. Fan out source gathering to a read-only subagent when the history is long (oh-my-claudecode:explore); keep synthesis in the lead.
  3. Reconcile: where sources conflict, the more authoritative source wins, and the conflict itself is reported.
  4. Write the answer with three labeled tiers — evidence (cited), inference (your reasoning from evidence, marked), guess (marked). End with the one action the answer most supports, or "no action".

Rules

  • Every claim about a past decision names its source in the same sentence.
  • Absence of evidence is reported as "no record found", never as "no reason".
  • The answer never edits code. If the user asks to act on it, hand off to execute or debug.
Files5
5 files · 8.2 KB

Select a file to preview

Overall Score

87/100

Grade

A

Excellent

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

92

Quality

86

Clarity

88

Completeness

82

Summary

The "why" skill guides agents to investigate code decisions through evidence rather than speculation. It teaches a systematic method for gathering human rulings, git archaeology, linked issues, and incident records—each claim labeled by confidence tier (evidence, inference, or guess). The skill is read-only: it gathers information, reconciles conflicts, and produces a cited answer, but never modifies code.

Detected Capabilities

git log querygit blame inspectiongit archaeologyfile readinggithub cli queriesobservability tool queries (Sentry, Datadog, Slack, Linear, Notion)subagent delegationsource reconciliationevidence classification

Trigger Keywords

Phrases that agents use to match this skill to user intent.

why was this builtcode archaeologydecision historytrace design intentlink issues to codevalidate before refactoraudit implementation decision

Risk Signals

INFO

Observability and external tool access (Sentry, Datadog, Slack, Linear, Notion) mentioned but scoped to read-only queries

SKILL.md, Sources section 4
INFO

Credential access acknowledged but explicitly made optional ('If a source needs credentials you do not have, say so and move on')

SKILL.md, Sources section 4
INFO

Subagent delegation to 'oh-my-claudecode:explore' referenced but no execution authority given—synthesis stays in lead agent

SKILL.md, Method section

Referenced Domains

External domains referenced in skill content, detected by static analysis.

github.com

Use Cases

  • , understand why code was built a particular way before refactoring or removing it
  • validate architectural decisions by tracing them to original intent before betting development effort
  • resolve design debates by grounding discussion in historical context rather than preference
  • surface missing evidence when investigating a controversial implementation
  • audit compliance or security decisions by retrieving original authorization records

Quality Notes

  • Epistemics reference is exceptionally thorough: defines five confidence tiers with specific phrasing guidance, addresses sycophancy trap and rationalization bias, and explicitly teaches how to surface contradictions without flattening nuance
  • Concrete playbooks for each source type (git archaeology, GitHub CLI, observability tools, design docs) enable agents to act immediately without guessing how to query
  • Clear boundary: the skill is read-only and explicitly forbids editing code ('The answer never edits code. If the user asks to act on it, hand off to `execute` or `debug`')
  • Investigator and synthesizer prompts are templated and reusable, supporting subagent delegation pattern
  • Strong guidance on avoiding common reasoning pitfalls: 'avoid rationalization', 'avoid the sycophancy trap', 'when evidence is missing, name each gap concretely'
  • Instructions are grounded in a real prior work (pstack) with proper attribution and ported prompts, adding credibility
  • Edge case handling: 'absence of evidence is reported as no record found, never as no reason' — prevents false confidence
  • Well-scoped 'When to use' section distinguishes this skill from general debugging or decision-making
Model: claude-haiku-4-5-20251001Analyzed: Nov 8, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Use Yeachan-Heo/why in your dev environment

Start a Developer trial

Command Palette

Search for a command to run...