why
/why
Find out why code, a feature or a value is the way it is. Searches decision records and tracker issues first, then git history with log -L, blame, pickaxe and PR bodies, then any connected chat, docs, monitoring, error or analytics source. Returns a cited answer that keeps what is recorded apart from what is inferred, and offers to file it as a wiki page or a decision record. Use when someone asks why X works this way, why Y was picked, where a threshold or constant came from, what caused a regression, or what a defensive check guards against.
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Find out why code, a feature or a value is the way it is. Searches decision records and tracker issues first, then git history with log -L, blame, pickaxe and PR bodies, then any connected chat, docs, monitoring, error or analytics source. Returns a cited answer that keeps what is recorded apart from what is inferred, and offers to file it as a wiki page or a decision record. Use when someone asks why X works this way, why Y was picked, where a threshold or constant came from, what caused a regression, or what a defensive check guards against.
Original author description
Find out why code, a feature or a value is the way it is. Searches decision records and tracker issues first, then git history with log -L, blame, pickaxe and PR bodies, then any connected chat, docs, monitoring, error or analytics source. Returns a cited answer that keeps what is recorded apart from what is inferred, and offers to file it as a wiki page or a decision record. Use when someone asks why X works this way, why Y was picked, where a threshold or constant came from, what caused a regression, or what a defensive check guards against.
How it works
- Steps
- Do
- Don't
SKILL.md preview
--- name: why description: Find out why code, a feature or a value is the way it is. Searches decision records and tracker issues first, then git history with log -L, blame, pickaxe and PR bodies, then any connected chat, docs, monitoring, error or analytics source. Returns a cited answer that keeps what is recorded apart from what is inferred, and offers to file it as a wiki page or a decision record. Use when someone asks why X works this way, why Y was picked, where a threshold or constant came from, what caused a regression, or what a defensive check guards against. disable-model-invocation: true --- # Why Code shows what it does, never why. A `retries = 3` can come from an outage, a copied line, or a customer call nobody wrote down. This skill searches the places where a reason gets written, in a fixed order. It answers with what was recorded, what is inferred, and what nobody wrote. Read [`epistemics.md`](epistemics.md) before you answer. Every claim gets one confidence tier from it, and the tier sets the wording. When `../teach/SKILL.md` or another skill started you with a question file and an output file, read the question there and write the answer to the output file. Skip step 6. That skill makes the offers. ## Steps ### 1. Pin the target and the question The target is a file range, a symbol, a feature, a constant or a named decision. The question is a rationale, a trade-off, a regression, a threshold or a history sweep. When the target is vague, guess from open files or recent edits. State the guess in one line and go on. A guess in the question, such as "I assume it's for performance?", is one hypothesis to test. Done when you can name the files with line ranges, the key symbols and the question in one sentence. ### 2. Search what was recorded Decision records and tracker issues come first. Their authors wrote the reason down on purpose. ```sh node scripts/find-docs.ts --type Decision --links-to <path> node scripts/find-docs.ts --type Decision --search "<words>" node scripts/find-docs.ts --links-to <path> node scripts/find-docs.ts --search "<words>" ``` Use two or three sets of words: the feature, the symbol, the problem. Read every hit in full, superseded records too, since they hold earlier reasoning. When `scripts/find-docs.ts` is missing, the repo was never set up. See `../setup/SKILL.md`. Grep `docs/` instead and say so in the answer. Then search the tracker with the **Search** operation from `docs/agents/issue-tracker.md`. Cover open and closed issues, with the same words. Run **List by label** with `adr` for decisions in flight. Read each relevant issue with the **View** operation, comments included. Done when every hit is read and every query is noted for the answer. ### 3. Dig through git history Build the code anchor, the commits that shaped the target and their PRs. ```sh git log -L <start>,<end>:<file> git log -L :<symbol>:<file> git blame -L <start>,<end> <file> git log --follow --oneline -- <file> git log -S '<exact value or string>' --oneline git show <hash> ``` - Trace back past the last commit. It is often a reformat or a move. - For a constant, run `git log -S` on its value to find the commit that added it. - Take PR numbers from merge subjects such as `(#1234)`, and ticket ids from bodies. Read each substantive PR with its review comments, for example `gh pr view <n> --json body,comments,reviews`. View the tickets as in step 2. - Read comments, `TODO` and `FIXME` notes, edge-case tests and `CHANGELOG` entries near the code. - A revert, a re-apply or a "fix for incident" commit marks a regression. Done when you have the commits, the PR and ticket numbers, and what each says. ### 4. Search the other connected sources Skip this step only when steps 2 and 3 give a written reason for the whole question, the Direct tier. Say so in the answer. List the MCP servers and CLIs connected in this session. Map each to one category in [`sources.md`](sources.md), such as chat, observability or an external tracker. - **One source.** Search it yourself with its playbook from `sources.md`. - **Two or more.** Start one subagent per source, all in one message, through the CLI's subagent tool, such as Agent. Run them on a fast model, such as Sonnet. Each subagent gets the path to [`investigator.md`](investigator.md), a scratchpad file with the code anchor and question, its source, and an output file path. It also learns whether the target looks defensive. Defensive code includes null checks, retries, timeouts, rate limits, feature flags and out-of-memory handlers. For it, add the incident queries from `sources.md` to every search. Done when every category has findings, empty queries or a skip reason. ### 5. Answer Write the answer in the shape of [`answer.md`](answer.md). Spot-check any citation you did not read yourself, and run its checks. When the user plans to change this code, end with its Preserve, Change, Avoid and Risk list. Done when every claim has a tier and a citation, and the gaps name the empty queries. ### 6. Offer to file it Offer this only when the answer took real digging and someone will ask again. Ask once with clickable options, through the CLI's question tool, such as AskUserQuestion. Put the best fit first. - **A decision record** with `h2xd:docs-adr`. Offer it when the answer documents a decision nobody recorded and meets that skill's three tests. Mark the record `proposed` unless a decider confirms it in this conversation. - **A wiki page** with `h2xd:docs-wiki`. Offer it for history, a regression or a threshold. List every PR, issue, commit and record you cited under `sources`. Done when the user chose one, or declined, or the answer was too thin to offer. ## Do - Quote the author's words with the exact location: record path, issue number, PR number, commit hash, or `file:line`. - Record every query. An empty search is a finding. - Show both sides when two sources disagree. - Name the person who would know when the record runs out. ## Don't - Don't cite code as evidence for its own intent. Cite what an author wrote, or mark the claim Inferred. - Don't stop at the newest commit. Follow `git log -L` back to the change that added the line. - Don't fill a gap with a plausible story. Put it under "What we don't know" with the searches you ran. - Don't let an investigator chase a lead into another source. It lists the lead and you assign it. - Don't write an `accepted` record from inference alone. File it as `proposed`, or as a wiki page.
Files in this package (5)
- SKILL.md 6 KB
- answer.md 3 KB
- epistemics.md 4 KB
- investigator.md 2 KB
- sources.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · h2xd/skills | 100 | MIT |
| sma1lboy/rove | 100 | MIT |
| chmonitor/chmonitor | 100 | GPL-3.0 |
| backnotprop/pstack | 100 | MIT |
| chhoumann/t3-pstack | 100 | MIT |
| arjitj2/open-pstack | 100 | MIT |
| painhardcore/pstack | 100 | MIT |
| guangshinhaha/shinstack | 100 | MIT |
| flora131/atomic | 100 | MIT |
Database snapshot: 13.11.2026 · package version 4bc4846740db (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100past-lives
Aang consulting his past lives (Roku, Kyoshi) for why things were decided. Use for why, /why, "why does X work this way", "why did we pick Y", design rationale, the history behind a regression, postmortem context, or where a threshold number came from. Queries every evidence… - 100git-master
Git expert — atomic commits with style detection, rebase/squash, and history archaeology (blame, bisect, pickaxe). Use for git operations. - 100git-master
Make atomic commits in the repo's own style, rebase or squash, and trace history with blame, bisect and pickaxe. Use when rebasing, squashing, cherry-picking or tracing history, or for one hand-picked commit; the commit skill splits, preflights and pushes the working tree. - 100arch-oracle
Use this skill when the user asks about git history, past decisions, why something was built a certain way, or needs to trace when/why a change was made. Provides historical awareness from git log, blame, and .ai/ memory. - 100git-archaeology
Recover intent from history when code looks wrong - blame to commit to pull request to linked ticket, plus revert and hotfix patterns - so you find out why something is the way it is before removing it. Use when code looks unnecessary or bizarre, before deleting anything odd,… - 95codebase-investigation
Read-only investigation that explains code and its history. Use for "how does X work", code walkthroughs before changing something, placement and ownership questions ("where should this live", "which package owns this", "is this the right layer"); for "why does X work this way",…