Add initial what happened skill

9a3cc84→main · 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:

rg -n -F "<distinctive snippet line>" -- <path>

• 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:

git blame --porcelain -L <start>,<end> -- <path>

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:

entire explain --commit <commit-sha> --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:

entire explain --checkpoint <checkpoint-id> --no-pager

3. If the default checkpoint view is still not enough, run:

entire explain --checkpoint <checkpoint-id> --full --no-pager

4. If --full fails and raw transcript is necessary to answer the user's question, run:

entire explain --checkpoint <checkpoint-id> --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:

What Happened:

Matches
- <path>:<start>-<end> -> commit <sha> | checkpoint <id>
```<language>
<matched code snippet>
```
- <path>:<start>-<end> -> commit <sha> | no Entire checkpoint
```<language>
<matched code snippet>
```
- <path>:<start>-<end> -> commit <sha> | checkpoint <id> unavailable
```<language>
<matched code snippet>
```
- <path>:<start>-<end> -> local uncommitted changes | no committed history
```<language>
<matched code snippet>
```

Then give one short section per distinct matching block:

Why
- <path>:<start>-<end>: <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.