# Add initial what happened skill `9a3cc84`→[main](/content/gh/entireio/skills/commits/main/index.html) · pfleidi · 2mo ago · 1 file · +219 added/-0 removed ## Sessions d654a3e78b3c View transcript ## Changes - plugins/entire/skills/what-happened --- name: What Happened description: > Explain why code looks the way it does by tracing the latest change for a file range or pasted snippet through `git blame` and cheap-first `entire explain` lookups. Use when the user asks what happened, is confused about a section of code, asks "wtf is going on", "why is this like this", "why was this changed", or wants provenance for a specific file block. --- # What Happened Use this skill when the user wants a provenance-focused explanation for a code block. Supported inputs: - `path:start-end` - `path` plus a pasted code snippet from that file ## Goal Find the most recent change blocks matching the user's target lines, list the matching commit hashes and checkpoint state, then summarize why each block was changed using the cheapest reliable context available. ## Rules 1. Do not guess about file contents or line numbers. Resolve the exact target lines before explaining anything. 2. Use the installed `entire` binary from `PATH`, not `./entire` from the current repo. 3. Prefer `git blame` for provenance and `entire explain --commit` for transcript-backed context. Do not use experimental `entire why` for this skill. 4. Do not manually hunt through `.git/entire-sessions/` or raw transcript files for commit provenance. If `entire explain` cannot provide transcript context, report the exact missing or unavailable state. 5. If the user provides a snippet, resolve it to exact line numbers before explaining anything. 6. If multiple blame blocks match, include all distinct ranges. Run expensive transcript lookups once per unique commit, not once per range. 7. Distinguish these states explicitly: - no checkpoint is referenced for the commit - a checkpoint is referenced but is unavailable locally or remotely - a checkpoint is available, but full transcript expansion failed - the code is untracked, uncommitted, or otherwise has no committed history 8. Keep the final explanation concise and block-focused. Do not summarize unrelated parts of the file. ## Workflow ### 1. Resolve the target block If the user gave `path:start-end`, use that range directly and read only that range from the file before explaining it. If the user gave a path and a snippet: - Pick the most distinctive exact line from the snippet and search the file with fixed-string matching to find candidate locations: ```bash rg -n -F "" -- ``` - Read the small candidate windows around each hit, not the whole file unless the file is already small or the search produces too many candidates to inspect efficiently. - Find the exact snippet in the candidate window. - Convert the match to `start-end` line numbers. - If whitespace differs but the code is otherwise identical, normalize leading indentation and trailing whitespace before deciding the snippet does not match. - If the snippet appears multiple times, report the ambiguity and list the candidate ranges instead of picking one silently. - If the snippet cannot be found exactly, say so plainly and stop rather than inferring a nearby match. ### 2. Gather provenance Run: ```bash git blame --porcelain -L , -- ``` If the command fails because the file is untracked, stop and say that the file is not tracked by git, so there is no committed history to trace. If blame reports an uncommitted pseudo-commit such as all zeroes or `Not Committed Yet`, mark those ranges as local uncommitted changes and do not run `entire explain` for them. If other target ranges resolve to real commits, continue with those committed ranges. Use the output to identify every blame block inside the target range. Group adjacent target lines that resolve to the same commit when they form one contiguous matched block. For each matching block, collect: - line range - matched code snippet from the current file for that exact range - commit hash - author/summary when helpful for commit-only context Collect the unique commit SHAs across all matching blocks while preserving each distinct range. After resolving the matching ranges, read the file contents for each matched block and keep the exact snippet so the final answer can show users which code each provenance entry refers to. ### 3. Explain each unique commit For each unique commit SHA, first run the cheapest lookup: ```bash entire explain --commit --short --no-pager ``` Use this to discover whether the commit has an associated checkpoint ID and to gather commit-level context. Do not use `--search-all` unless the user explicitly asks to widen a failed lookup; it removes branch/depth limits and may be slow. If this command fails, do not scan raw session files. Use `git show --no-patch` for commit metadata, mark the explanation as commit-only context, and report that Entire transcript lookup failed. Include the command error only if it helps the user fix the issue, such as authentication or missing remote configuration. Then use the cheapest sufficient detail: 1. If `--commit --short` gives enough context, use it. 2. If it reveals a checkpoint ID but more detail is needed, run: ```bash entire explain --checkpoint --no-pager ``` 3. If the default checkpoint view is still not enough, run: ```bash entire explain --checkpoint --full --no-pager ``` 4. If `--full` fails and raw transcript is necessary to answer the user's question, run: ```bash entire explain --checkpoint --raw-transcript --no-pager ``` Use the collected output to answer: - what the agent was trying to do - why this block changed - any constraint, bug, edge case, or refactor pressure that caused the final code If the commit has no checkpoint ID, use commit-level context and the code block itself, clearly marked as "commit-only context; no Entire checkpoint was referenced." If a checkpoint ID is present but `entire explain --checkpoint` cannot load it, keep the checkpoint ID in the answer and say "checkpoint was referenced, but the checkpoint was not available locally or remotely." Include the command error only if it helps the user fix the issue, such as authentication or missing remote configuration. If the checkpoint loads but `--full` or `--raw-transcript` fails, say that checkpoint metadata was available but transcript expansion failed, then answer from the default checkpoint view. Map each unique commit explanation back to every target range blamed to that commit. ## Response format Start with a short provenance summary: ````text What Happened: Matches - :- -> commit | checkpoint ``` ``` - :- -> commit | no Entire checkpoint ``` ``` - :- -> commit | checkpoint unavailable ``` ``` - :- -> local uncommitted changes | no committed history ``` ``` ```` Then give one short section per distinct matching block: ```text Why - :-: <2-4 sentence explanation of why this block changed last time> ``` Snippet guidance: - Prefer the exact matched lines from the file. - Keep snippets tight to the matched block; avoid unrelated surrounding code unless needed for readability. - If the block is long, include the smallest contiguous excerpt that still lets the user recognize it and say that it was truncated.