> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Investigate Why Code Exists

> Trace code history with entire blame, entire why, and entire investigate.

Use this tutorial when you find surprising code and need to know whether it is intentional, who changed it, and what context should be preserved before you refactor.

In this tutorial, you will use `entire blame`, `entire why`, and `entire investigate` to answer:

> Why does `/leaderboard` open the leaderboard directly instead of going through the game menu?

## Prerequisites

Before you start, make sure you have:

* [Git installed](/installation)
* [Entire installed](/installation)
* Entire 0.7.7 or higher
* At least one [supported AI agent](/agents/overview) configured

## Set Up the Repo

Planetfall is a sample game repo with a rich history of [checkpoints](/guides/checkpoints/overview). Clone it to get started:

```bash theme={null}
git clone https://github.com/blackgirlbytes/planetfall-seed-signalkit.git
cd planetfall-seed-signalkit
```

## Scenario

You are new to the codebase, and you have been asked to clean up the leaderboard experience. While browsing the app, you notice there are two ways to open the leaderboard: players can click **Leaderboard** from the game menu, but `/leaderboard` also opens the leaderboard directly.

Before changing either path, you need to know whether the direct route is intentional or leftover routing code.

The code below handles the direct `/leaderboard` route:

```text src/main.js:278-281 theme={null}
278  if (isLeaderboardRoute) {
279    document.body.classList.add("leaderboard-route");
280    showTitleLeaderboard();
281  } else if (!requestedView && !params.get("level") && !endShortcut) {
```

## Trace the Attribution

Before deciding whether the direct route is duplicate routing code, start with the code history.

<Frame>
  <div style={{ position: 'relative', paddingTop: '64.67065868263472%' }}>
    <iframe src="https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/ab2d696d319f2f9d1643c9e57f8132a2/iframe?muted=true&loop=true&autoplay=true&poster=https%3A%2F%2Fcustomer-0x5hsk8lh27fm00g.cloudflarestream.com%2Fab2d696d319f2f9d1643c9e57f8132a2%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600" title="Entire blame demo" loading="lazy" style={{ border: 'none', position: 'absolute', top: 0, left: 0, height: '100%', width: '100%', borderRadius: '0.5rem' }} allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture" allowFullScreen />
  </div>
</Frame>

To find out why `/leaderboard` opens the leaderboard directly, run [`entire blame`](/cli-reference/blame) for line `279`, where the app switches into the standalone leaderboard route:

```bash theme={null}
entire blame src/main.js --line 279
```

The output shows that line `279` last changed in a mixed-attribution commit labeled `[MX]`, meaning the commit included both agent-attributed and human-attributed changes:

```text theme={null}
Line  Tag   Agent  Author          Checkpoint    Content
279   [MX]  Codex  blackgirlbytes  bfc2c1df9e4b  document.body.classList.add("leaderboard-route");
```

The direct route points to a checkpointed commit. Next, find out why the change was made.

## Find the Reason

Run [`entire why`](/cli-reference/why) on line `279`:

```bash theme={null}
entire why src/main.js:279
```

The output gives you a brief overview of the line's history, including the checkpoint, session, commit, and original prompt:

```text theme={null}
Line 279 in src/main.js
    document.body.classList.add("leaderboard-route");

[MX] by Codex - gpt-5.5 - checkpoint bfc2c1df9e4b - session 019edf9f - commit 35cdcfb6
Prompt: "we want to be able to go the route /leaderboard and it renders the leaderboard there"

Full context: entire checkpoint explain bfc2c1df9e4b
```

The output also suggests a follow-up command. Run [`entire checkpoint explain`](/cli-reference/checkpoint#checkpoint-explain) with `--generate` to get the checkpoint's intent and outcome:

```bash theme={null}
entire checkpoint explain bfc2c1df9e4b --generate
```

You should see an explanation like this:

```text theme={null}
## Intent

Add a direct browser route /leaderboard that renders the existing leaderboard
experience without requiring navigation through the title menu.

## Outcome

Implemented the /leaderboard route by patching main.js to detect the path and
boot directly into leaderboard mode, adding CSS for standalone overlay behavior,
and adding vercel.json with SPA rewrite rules.
```

## Investigate the Decision

You learned why the route was added, but you still need to understand how the current code supports that decision. Use [`entire investigate`](/cli-reference/investigate) to inspect the route, the menu path, and the leaderboard panel together.

Create a short seed doc with the evidence you found:

```bash theme={null}
cat > leaderboard-route-investigation.md <<'EOF'
# Investigation: direct leaderboard route

Question:
Why does /leaderboard open the leaderboard directly instead of going through the game menu?

Evidence:
- src/main.js opens the leaderboard directly when the path is /leaderboard.
- entire blame ties src/main.js:279 to a mixed-attribution commit with a checkpoint.
- entire why points src/main.js:279 to the direct leaderboard route work.

Please inspect src/main.js, src/titleScreen.js, and src/leaderboardPanel.js.
Explain why the direct /leaderboard route exists, what user or demo workflow it supports,
and what should be preserved if we refactor the leaderboard.
EOF
```

Run the investigation:

```bash theme={null}
entire investigate leaderboard-route-investigation.md --max-turns 1
```

On first run, Entire may ask which agents should participate. Pick the agents configured for your Entire setup.

<Note>
  `entire investigate` is experimental. It appears under labs while the workflow is still being refined.
</Note>

## Read the Findings

Browse saved investigations:

```bash theme={null}
entire investigate --findings
```

Then print a run:

```bash theme={null}
entire investigate show RUN_ID
```

In this example, `entire investigate` found that the direct route was intentional:

```text theme={null}
## Findings

### 1. The direct route is intentional

src/main.js normalizes the path and sets:

  isLeaderboardRoute = normalizedPath === "/leaderboard"

At boot, the app checks that route before showing the title screen:

  if (isLeaderboardRoute) {
    document.body.classList.add("leaderboard-route");
    showTitleLeaderboard();
  } else if (!requestedView && !params.get("level") && !endShortcut) {
    titleScreen.show();
  }

When the path is /leaderboard, the title screen's show() is never called.
The panel opens directly. The checkpoint intent says the route should render
the existing leaderboard experience without requiring navigation through the
title menu.
```

You started with a surprising line of code, traced who changed it, found the checkpoint context, and used `entire investigate` to confirm what the route supports. Now you know `/leaderboard` is intentional and what behavior to preserve before refactoring it.

## Troubleshooting

<AccordionGroup>
  <Accordion title="unknown command &#x22;blame&#x22; or &#x22;why&#x22;">
    Update Entire by following the [updating guide](/updating). Make sure you are on Entire 0.7.7 or higher.
  </Accordion>

  <Accordion title="entire blame does not show a checkpoint">
    Make sure you cloned the sample repo with its checkpoint metadata branch. Run `git branch -r | grep 'entire/checkpoints/v1'` to confirm the remote checkpoint branch is present.
  </Accordion>

  <Accordion title="entire why says no checkpoint is linked">
    That can be a valid result. Some lines come from commits that were not linked to Entire session context. Use Git history, tests, and `entire investigate` to continue from there.
  </Accordion>

  <Accordion title="entire investigate asks me to configure agents">
    That is expected on first run. Pick the agents configured for your Entire setup. You can re-open the picker later with `entire investigate --edit`.
  </Accordion>
</AccordionGroup>

## Continue with

<CardGroup cols={2}>
  <Card title="Search Past Agent Work" icon="search" href="/learn/search-past-agent-work">
    Search checkpoints and sessions by meaning, phrase, or prior context.
  </Card>

  <Card title="checkpoint Command Reference" icon="terminal" href="/cli-reference/checkpoint">
    List, explain, search, and inspect checkpoints from the CLI.
  </Card>
</CardGroup>