Entire

Explains the intent behind source code by finding original session transcripts. Use /explain with a function, file, or line of code to understand why it exists.

# Explain Intent

Explain the intent behind source code by tracing it back to the original conversation where it was created. Works with:

- **Functions** — Why does this function exist? What problem was it solving?
- **Files** — What's the purpose of this file? What requirements drove its creation?
- **Line changes** — Why was this specific line added or modified?

## Response Format

Begin the first response to this skill invocation with the line:

`Entire Explain:`

followed by a blank line, then the content.

- Apply the header to the **first response of the invocation only.** Do not re-print it on follow-up turns within the same invocation (e.g. after the user answers a clarifying question).
- Do **not** include the header on error or early-exit responses (e.g. "Entire CLI is required but not installed", "this file is not tracked by git", "no session transcript was found for this commit"). The header's presence should signal that the skill ran and produced real output.

## Process

1. Verify the `entire` CLI is installed by running `entire version`.
   - If the command is not found, stop and tell the user: "The Entire CLI is required but not installed. Install it from https://entire.io/docs/cli and try again."
2. Use a Haiku agent to identify the commit that introduced the code via git blame or git log.
   - If the file is not tracked by git, stop and tell the user: "This file is not tracked by git, so I can't trace its history."
   - If git blame returns no useful result (e.g., the code is uncommitted), stop and tell the user: "This code hasn't been committed yet, so there's no history to trace."
3. Use a Sonnet agent to read the session transcript via `entire explain --no-pager --commit COMMIT_SHA`.
   - If the command fails or returns no transcript, stop and tell the user: "No session transcript was found for this commit. It may have been created outside of an Entire session (e.g., a manual commit)."

Use when the user wants to find prior work, checkpoints, or agent conversations by topic, repo, branch, author, or recent time window

# Search Checkpoints

Use `entire search` to find relevant checkpoints before guessing from memory.

## Response Format

Begin the first response to this skill invocation with the line:

`Entire Search:`

followed by a blank line, then the content.

- Apply the header to the **first response of the invocation only.** Do not re-print it on follow-up turns within the same invocation (e.g. after the user answers a clarifying question).
- Do **not** include the header on error or early-exit responses (e.g. "Entire CLI not installed", "authentication required", "no matches"). The header's presence should signal that the skill ran and produced real output.

## When to Use

- The user asks things like "have we done this before?", "search past work", "find the previous implementation", or "look for checkpoints about X"
- You need prior context from another branch, repo, author, or recent time period
- You want likely matches first, then a deeper transcript read only for the best hit

Do not use this for the current active session. Use `session-handoff` for that.

## Process

1. Run a focused search with JSON output so results are easy to inspect:

```bash
entire search "<query>" --json
```

Add filters when the user already gave them or when the first search is too broad:

```bash
entire search "<query>" --json --repo owner/name --branch branch-name --author "Name" --date week
```

Inline filters are also supported in the query: `author:<name>`, `date:<week|month>`, `branch:<name>`, `repo:<owner/name>`, `repo:*`.

2. Review the top matches and summarize the likely candidates for the user. Do not dump raw JSON unless they ask for it.

3. If the user wants details on a specific result, open the checkpoint with:

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

If `--full` fails, fall back to:

```bash
entire explain --checkpoint <checkpoint-id> --raw-transcript --no-pager
```

## Search Heuristics

- Start with the user's domain terms, feature name, error text, file name, or ticket ID
- Prefer narrower searches before increasing `--limit`
- Add `--repo` or `repo:*` explicitly when repository scope matters
- If there are no useful hits, broaden in this order: remove branch filter, widen date, simplify query terms

## Failure Modes

- If search says authentication is required, tell the user to run `entire login`
- If there are no matches, say that clearly and mention the filters or query terms you tried
- If the user really wants the current session, switch to `session-handoff` instead of searching checkpoints

Use when the user wants to continue work from one agent in another agent, inspect recent sessions, or summarize a saved session or checkpoint for handoff

# Hand-Off Session

## Response Format

Begin the first response to this skill invocation with the line:

`Entire Session Handoff:`

followed by a blank line, then the content. The header applies to the full compaction-summary flow, including the "Unanswered Question" branch (which is still a successful run — the skill summarized the transcript and surfaced the question).

- Apply the header to the **first response of the invocation only.** Do not re-print it on follow-up turns within the same invocation (e.g. after the user answers the surfaced unanswered question).
- Do **not** include the header on error or early-exit responses (e.g. no `.git/entire-sessions/` directory, no sessions found after filtering, transcript file missing at the path the session JSON points to). The header's presence should signal that the skill ran and produced real output.

## STOP — Read these rules before doing ANYTHING

1. **Do NOT ask clarifying questions.** Auto-detect the session and read the transcript.
2. **Do NOT run** `entire sessions list`, `entire sessions info`, `entire explain --session`, `git log`, `git status`, `git branch`, `ps aux`, or any other exploratory commands. They waste time and don't give you the transcript.
3. **Do NOT say** "Would you like me to continue?" or "Let me know if you want me to pick this up." Just read the transcript and start working. (Exception: if the previous agent asked the user a question that was never answered, you MUST ask the user that question before proceeding.)
4. **Do NOT summarize the session as having "0 turns" or "no progress"** without first reading the actual transcript file. The `entire` CLI metadata often undercounts — the transcript is the source of truth.
5. **Skip your own session.** Your agent (e.g. Claude Code) also has a session in `.git/entire-sessions/`. Exclude any session whose `agent_type` matches your own agent type from the results.

## Flow: Active / current session handoff

When the user says "current", "active", or just "hand off this session":

### Step 1: Run `entire status`

```
entire status
```

This returns the active session ID. If the user mentioned an agent name (e.g. "codex"), look for that agent's session in the output.

### Step 2: Find the transcript path

Read the session file at `.git/entire-sessions/<session-id>.json` using the Read tool:

```
Read: .git/entire-sessions/<session-id>.json
```

The file looks like this:
```json
{
  "session_id": "019d730f-e099-7910-a946-b5b20e2cfafc",
  "agent_type": "Codex",
  "phase": "active",
  "started_at": "2026-04-09T09:25:21.725231-07:00",
  "last_interaction_time": "2026-04-09T09:25:21.725657-07:00",
  "transcript_path": "/Users/alisha/.codex/sessions/2026/04/09/rollout-....jsonl",
  "last_prompt": "create solitaire game"
}
```

Extract the `transcript_path` field. This is the path to the full conversation transcript.

**Fallback:** If `entire status` doesn't give you a session ID, or the session JSON doesn't exist, use the Glob tool to find all `.git/entire-sessions/*.json` files, read them, and pick the most recent one (by `last_interaction_time` or `started_at`). Filter by agent name if the user specified one. Always exclude sessions matching your own agent type.

### Step 3: Extract and summarize the transcript

**Phase A — Extract raw transcript** (do NOT show this to the user):

```bash
grep -E '"type":"(message|function_call|user|assistant)"' <transcript_path> | cut -c1-2000
```

If the output exceeds ~500 lines, read the **last 100 lines** (final state) and **first 20 lines** (original task):

```bash
grep -E '"type":"(message|function_call|user|assistant)"' <transcript_path> | tail -100 | cut -c1-2000
grep -E '"type":"(message|function_call|user|assistant)"' <transcript_path> | head -20 | cut -c1-2000
```

**Phase B — Produce a compaction summary.** Internally process the extracted transcript and produce a structured summary with these sections:

1. **Task Overview** — The user's core request, success criteria, and any stated constraints or clarifications.
2. **Current State** — Completed work: files created/modified, key decisions made, artifacts produced.
3. **Important Discoveries** — Technical constraints uncovered, rationale behind decisions, errors hit and their resolutions, failed approaches and why they failed.
4. **Next Steps** — Specific remaining actions, blockers, and priority ordering.
5. **Context to Preserve** — User preferences, domain-specific details, and commitments made during the session.
6. **Unanswered Question** (only if applicable) — If the previous agent's last message asked the user a question or presented options that were never answered, capture it here exactly as asked.

Be concise but complete — err on the side of including information that would prevent duplicate work or repeated mistakes.

### Step 4: Present summary, then continue

Show the compaction summary from Phase B to the user.

**Critical rule — unanswered questions go to the user, not you.** If section 6 (Unanswered Question) exists, present that question to the user and wait for their answer. Do NOT answer it yourself or pick a default. The user is the decision-maker.

If there is no unanswered question, **immediately pick up the work** — start planning, coding, or doing whatever the next step is. Do not ask permission.

## Flow: Checkpoint handoff (user gives a checkpoint ID)

1. Run `entire explain --checkpoint <checkpoint-id> --full --no-pager`
2. If `--full` fails, fall back to `entire explain --checkpoint <checkpoint-id> --raw-transcript --no-pager`
3. Extract conversation content from ALL session transcripts (do NOT show raw output to the user):

```bash
grep -rE '"type":"(message|function_call|user|assistant)"' <transcript_dir_or_files> | cut -c1-2000
```

For large checkpoints with many sessions, focus on the last 100 lines per transcript to understand final state, and the first 20 lines for the original task.

4. Produce and present a compaction summary using the same 5-section format from Step 3 Phase B above, then continue.

Resolve checkpoint repos in order: explicit override → local `entire/checkpoints/v1` branch → `.entire/settings.json` `checkpoint_remote` → nearby local clone.

## Flow: No specific request (bare invocation)

Use the Glob tool to find `.git/entire-sessions/*.json`. Read each file, exclude your own agent type, pick the most recent by `last_interaction_time`. Read the transcript at `transcript_path`. Summarize and continue.

## Agent name filtering

Words like "codex", "claude", "kiro", "gemini" in the user's request are **filters** for session selection. Match them case-insensitively against the `agent_type` field (fall back to `agent` field). Never invoke another agent's CLI.

>

# What Happened

Use this skill when the user wants a provenance-focused explanation for a code block.

Supported inputs:

- `path:line`
- `path:start-end`
- `path` plus a pasted code snippet from that file

If the user asks a vague provenance question without a file path, line range, or pasted
snippet, ask for the target code and stop without running commands or using the header.

## 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
best available context. When checkpoint-backed context is unavailable, still
explain what the current code does as an explicit fallback and clearly mark that explanation
as not checkpoint-backed.

## 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. Use this skill for latest-change provenance on a specific block. For broad original intent
   of a symbol, file, or feature, prefer the `explain` skill.
5. 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.
6. If multiple blame blocks match, include all distinct ranges. Deduplicate commit hashes
   before running `entire explain`; run transcript lookups once per unique commit, not once
   per range. Also deduplicate checkpoint IDs before expanding checkpoint transcripts; run
   checkpoint expansion once per unique checkpoint, not once per commit or 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 and raw transcript
     expansion was not explicitly requested
   - Entire transcript lookup failed (the `entire explain` command itself errored)
   - the code is untracked, uncommitted, or otherwise has no committed history
   - any other provenance command fails after the target code was resolved
8. For every resolved code block, include either checkpoint-backed history or a fallback
   explanation of what the current code does. Label fallback explanations as "not
   checkpoint-backed" and do not imply intent or historical rationale from checkpoints.
9. Treat `entire explain` command output as intermediate source material for summarization.
   Do not paste raw command output or full transcripts into the user response unless the user
   explicitly asks for raw output. Include only short error excerpts when they help the user fix
   a failed lookup.
10. 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 did not provide a file path plus exact line/range or pasted snippet, ask them for
the target code and stop. Do not run commands or use the `Entire What Happened:` header.

If the user gave `path:line` or `path:start-end`, use that line or range directly and read
only that target from the file before explaining it. If the path does not exist, the file
cannot be read, or the line/range is outside the file, say so plainly and stop without using
the `Entire What Happened:` header.

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
grep -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. Do not use the `Entire What Happened:` header for this
  unresolved-input response.
- If the snippet cannot be found exactly, say so plainly and stop rather than inferring a nearby
  match. Do not use the `Entire What Happened:` header for this unresolved-input response.

### 2. Gather provenance

Only run blame after the target has been resolved to actual line numbers in the current file.
Do not run `git blame -L` against an unresolved pasted snippet, inferred nearby block, symbol
name, or approximate range.

Run:

```bash
git blame --porcelain -L <start>,<end> -- "<path>"
```

If the command fails because the file is untracked, mark the whole target range as an untracked
file with no committed history, keep the exact snippet for that range, and continue to fallback
code behavior analysis.

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 provenance or fallback context

Collect the unique real commit SHAs across all matching blocks while preserving each distinct
range. Exclude untracked and local uncommitted pseudo-commits from this set. Build a map from
commit SHA to all target ranges blamed to that commit. Do not run `entire explain` separately
for multiple ranges that share the same commit.

If the resolved target spans more than 5 unique real commits, stop before running `entire
explain`. Report the matched ranges and ask the user to narrow the range or confirm the deeper
lookup. Do not use the `Entire What Happened:` header for this confirmation response.

Keep the exact snippets from the target-resolution read so the final answer can show users
which code each provenance entry refers to. Only reread a matched block if the snippet for
that range was not already captured.

### 3. Explain each unique commit

For each unique commit SHA in that map, run exactly once:

```bash
entire explain --commit <commit-sha> --no-pager
```

When there are multiple unique commits, run those independent commit lookups in parallel when
the agent environment supports parallel tool calls.

Use this output to answer the question and identify the checkpoint state. 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 run extra commit metadata lookups and do not scan raw session
files. Mark the range for fallback code behavior analysis 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.

If the commit view reveals a checkpoint ID but is still not enough to answer the user's
question, collect the checkpoint ID for expansion. Deduplicate checkpoint IDs across all
commit views before running checkpoint lookups; if several commits reference the same
checkpoint, expand that checkpoint once and map the result back to every relevant range.

For each unique checkpoint ID that needs more detail, run:

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

Do not run raw transcript expansion automatically. If `--full` fails or is insufficient,
mark the affected ranges for current-code fallback analysis unless the user explicitly asked
for raw transcript detail. Only when explicitly requested, run:

```bash
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

Do not show the raw `entire explain` output by default. Summarize only the relevant parts tied
to the target ranges.

If the commit has no checkpoint ID, use only the commit-level context returned by
`entire explain --commit` for provenance and mark the range for fallback code behavior
analysis. Clearly state "no checkpoint-backed summary; 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 <id> 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` fails, say that checkpoint metadata was available but
full transcript expansion failed. If raw transcript detail was not explicitly requested, say
it was not expanded automatically. Answer checkpoint-backed facts from the `entire
explain --commit` output, and use current-code fallback analysis for anything that output
cannot support.

Map each unique commit explanation back to every target range blamed to that commit.

### 4. Add fallback code behavior analysis when needed

For any resolved range that falls into one of the states listed in Rule 7 where
checkpoint-backed context is unavailable, still answer what the current code does.

Use only source-backed analysis:

- Read the target block and the smallest necessary surrounding scope, such as the enclosing
  function, type, imports, or constants.
- Use `grep -n -F` to inspect direct call sites or definitions only when the block cannot be
  understood from local context.
- Explain observable behavior, inputs, outputs, side effects, and important branches.
- Do not present this as historical intent, checkpoint rationale, or an agent transcript summary.
- State what cannot be known from current code alone.

## Response format

Begin the first successful resolved-code response to this skill invocation with the line:

`Entire What Happened:`

followed by a blank line, then the content.

- Apply the header to the **first successful resolved-code response of the invocation only.**
  If an earlier unresolved-input response omitted the header and the user later disambiguates
  the target, include the header on the resolved-code response. Do not re-print it on later
  follow-up turns within the same invocation.
- Do **not** include the header on unresolved-input responses (e.g. snippet not found,
  ambiguous snippet, invalid path or range). If the target code was resolved but no
  checkpoint-backed context exists, still use the header and clearly label the answer as
  current-code fallback analysis rather than a checkpoint summary.
- After the header, include exactly one short, original, non-lyrical "Tell me why" line
  randomly chosen from the examples below. Do not quote, paraphrase, or imitate Backstreet
  Boys lyrics or any other song lyrics.

Allowed examples:

- `Tell me why: the blame points here.`
- `Tell me why: the diff left a trail.`
- `Tell me why: the context starts here.`

Start with a short provenance summary using one status per range from the states in Rule 7:

````text
Entire What Happened:

Tell me why: the blame points here.

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> | Entire transcript lookup failed
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> commit <sha> | checkpoint <id> unavailable
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> commit <sha> | checkpoint <id> metadata only, transcript expansion failed
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> local uncommitted changes | no committed history
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> untracked file | no committed history
  ```<language>
  <matched code snippet>
  ```
````

For checkpoint-backed ranges, give one short section per distinct matching block:

```text
Why
- <path>:<start>-<end>: <2-4 sentence explanation of why this block changed last time>
```

For ranges without checkpoint-backed context, use this separate section instead:

```text
Current-code fallback (not checkpoint-backed)
- <path>:<start>-<end>: <2-4 sentence explanation of what the current code does, plus any
  limits on what can be inferred without checkpoint history>
```

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.

When the input was a pasted snippet, include the resolved line range in the answer.

## Trigger phrases

This skill should trigger for questions like:

- "wtf is going on with this code"
- "tell me why this code is like this"
- "tell me why this code is like that"
- "tell me why this was changed"
- "what happened here"
- "what happened to this block"
- "why is this code like this"
- "why does this code look like this"
- "why does this look weird"
- "why was this changed"
- "why does this exist"
- "why was this written this way"
- "what is the history behind this code"
- "help me understand this block"
- "what changed here and why"

Especially trigger when the user includes:

- a single file line like `cmd/entire/cli/explain.go:103`
- a file range like `cmd/entire/cli/explain.go:103-107`
- a file path plus a pasted code snippet