Reconstruct and explain WHY the code in $ARGUMENTS exists — the problem it solves and the decision behind it — using git history as primary evidence. This is a read-only investigation; make no edits.
Resolve the target
- If
$ARGUMENTSis empty, ask the user to name a file, afile:linerange, or a symbol, then stop. - If it's a file path, target the whole file (or the most relevant region if large).
- If it's a symbol (function, class, const, config key), locate its definition with Grep/Glob first, then work on those exact lines. If it resolves to several places, list them and ask which, or investigate the primary one and say so.
- Confirm git is usable before relying on history:
git rev-parse --is-inside-work-treemust succeed andgit ls-files --error-unmatch <file>must confirm the file is tracked. If either fails (no repo, untracked/new file, submodule boundary), say so up front and switch to code-only reasoning — explain intent from the code, comments, and tests, and mark the entire answer as inferred.
Method (in order)
- Read the target lines plus enough surrounding context to understand what the code actually does before asking why. Note anything surprising: a workaround, a guard, a magic number, a non-obvious ordering, a
// TODO/// HACK/// FIXME. - Get the change history of exactly those lines, following renames. On a long history don't dump every diff: first list the commits cheaply with
git log -L <start>,<end>:<file> -s(the-s/--no-patchsuppresses diffs; for whole-file scope usegit log --oneline --follow -- <file>), then read full patches (drop-s, orgit log --follow -p -- <file>) only for the oldest few commits that touch the code — that is where the reason was introduced. Bound runaway output with-n <N>or a--since=<date>window. git blame -w -M -C <file> -L <start>,<end>to find the commit that introduced or last meaningfully changed each line (-wignores whitespace,-M/-Csee through moves/copies so you skip reformatting commits).- For each relevant commit:
git show <sha>to read the full message, the co-changed files, and the diff. The intent usually lives in sibling changes, not the one line. - Follow the trail outward: extract PR/issue/ticket IDs (
#123,JIRA-456), commit-message trailers (Fixes:,Ref:,See:,Closes:,Co-authored-by:), and anygit revert/This reverts commit <sha>links. Ifghis available and the project is on GitHub, rungh pr view/gh issue viewfor the discussion. Check whether the line was itself a fix to an earlier commit (git log --onelinearound it) — a revert or hotfix is the real story. - Cross-check against in-repo context: CHANGELOG, ADR/design docs, nearby tests (a test named for the case proves the intent), and code comments. A commit that references a failing test or a customer bug is stronger evidence than a vague message.
Distinguish evidence from inference
- Label each claim: stated in a commit/PR (quote the sha and the line), inferred from surrounding code and tests, or unknown.
- Prefer the earliest commit that establishes the reason over later cosmetic touches.
- If history is squashed, shallow, force-pushed, or the line predates the repo (initial import), say so plainly and fall back to code-level reasoning.
Output
- What it does — one or two sentences on the code's behavior.
- Why it exists — the decision and the problem it solved, tied to specific evidence.
- Evidence — bullets of
sha (short) — message summaryand anyPR/issue #you used, each marked stated vs. inferred. - Still standing? — whether the original reason still applies, or if the referenced bug/constraint/dependency looks obsolete. Only flag this when history supports it.
Rules
- Never guess intent and present it as fact. If the history is silent, say "history doesn't explain this" and give your best code-based hypothesis, marked as such.
- Never invent commit hashes, PR numbers, author names, or dates — cite only what the commands returned.
- Don't editorialize the code's quality; explain the decision, don't grade it.
- Keep it tight: a senior engineer should be able to act on the answer in under a minute.