Skip to content

ykorovko/dotagents / skills/why

Investigate why code or a design exists using repository history and available contextual sources. Use only when the user explicitly asks about rationale, tradeoffs, regressions, historical constraints, or the origin of a threshold or behavior.

Why

Investigate the motivation and constraints behind code. Separate what the record states from what the evidence merely suggests. Code can show what happens; it rarely proves why someone chose it.

Treat this as a read-only investigation. Do not modify files, external systems, tickets, or documents unless the user separately authorizes those changes.

Establish the question

Identify the code, behavior, decision, or threshold the user is asking about. Treat any explanation embedded in the question as a hypothesis, not a conclusion.

Anchor the investigation with:

  • Relevant files, line ranges, and symbols
  • Commits that introduced or substantially changed the behavior
  • PR, issue, incident, or document identifiers found in history
  • The time window in which the decision was made

Use repository-native history tools such as git blame, git log --follow, git show, and repository search. Use a hosting CLI or connector only when it is already available and authorized.

Search for evidence

Start with source control, then follow identifiers into other sources that are available and relevant:

  • Pull requests and code review discussions
  • Issue or ticket trackers
  • Design documents, ADRs, specifications, and postmortems
  • Team chat and meeting records
  • Runtime metrics, logs, traces, and incident timelines
  • Error tracking and release data
  • Product analytics or warehouse data

Read references/source-playbook.md to select the relevant source guides. Always use the code-archaeology guide for repository history, then read only the playbooks that match sources available to the current investigation. If the target looks defensive, also read the incident and postmortem guide.

Do not assume these sources exist or require connectors the environment does not provide. Do not install tools, request new access, or search unrelated private histories. Record unavailable sources as coverage gaps.

Scale the search to the question. A narrow decision with an explicit commit message may need only source control. A disputed rationale, incident-driven guard, or unexplained numeric threshold may justify several evidence sources. Parallelize independent searches only when the harness supports delegation and the user permits it. When delegating, read references/investigator-prompt.md, give each investigator one source category, and keep every investigation read-only.

For each source, record what you searched, what you found, contradictions, and useful null results. An empty search is evidence only about the query and scope you actually ran, not proof that no rationale exists.

Calibrate claims

Read references/epistemics.md before drawing conclusions. Apply its confidence tiers and phrasing rules.

Key constraints:

  • Cite claims about intent with a commit, PR, ticket, document, message, incident, or code comment.
  • Do not use current code behavior as evidence of its own motivation.
  • Surface contradictions rather than choosing the tidiest story.
  • Label interpretations and competing hypotheses explicitly.
  • Say what remains unknown and which sources were unavailable.

Report

When consolidating findings from several sources or investigators, read references/synthesizer-prompt.md. The coordinating agent may apply it directly. A separate synthesizer is optional and requires the same delegation support and permission; when using one, fill the template with the contents of references/epistemics.md, not an unresolved relative link.

Adapt the structure to the question, but keep evidence and inference separate:

  • Question and code anchor. The target files, symbols, and decision under investigation.
  • What the record says. Direct or strongly supported claims with adjacent citations.
  • What the evidence suggests. Inferences with the reasoning chain and calibrated language.
  • Competing hypotheses. Plausible alternatives when the evidence does not select one.
  • What remains unknown. Specific unanswered questions and coverage gaps.
  • Sources consulted. Queries, items reviewed, null results, and unavailable sources.
  • Confidence. A short summary of which conclusions are direct, supported, inferred, speculative, or unknown.

If the investigation precedes a code change, finish with the constraints the evidence says to preserve, risks to check, and assumptions that need confirmation. Do not recommend preserving historical behavior merely because it is old.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexUnverifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall