Investigate Why Code Exists

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
Entire installed
Entire 0.7.7 or higher
At least one supported AI agent configured

Set Up the Repo

Planetfall is a sample game repo with a rich history of checkpoints. Clone it to get started:

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:

src/main.js:278-281

if (isLeaderboardRoute) {
  document.body.classList.add("leaderboard-route");
  showTitleLeaderboard();
} 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.

To find out why /leaderboard opens the leaderboard directly, run entire blame for line 279, where the app switches into the standalone leaderboard route:

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:

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 on line 279:

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:

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 with --generate to get the checkpoint’s intent and outcome:

entire checkpoint explain bfc2c1df9e4b --generate

You should see an explanation like this:

## 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 to inspect the route, the menu path, and the leaderboard panel together. Create a short seed doc with the evidence you found:

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:

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.

entire investigate is experimental. It appears under labs while the workflow is still being refined.

Read the Findings

Browse saved investigations:

entire investigate --findings

Then print a run:

entire investigate show RUN_ID

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

## 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

unknown command "blame" or "why"

Update Entire by following the updating guide. Make sure you are on Entire 0.7.7 or higher.

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.

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.

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.

Investigate Why Code Exists

Prerequisites

Set Up the Repo

Scenario

Trace the Attribution

Find the Reason

Investigate the Decision

Read the Findings

Troubleshooting

Continue with

Search Past Agent Work

checkpoint Command Reference

​Prerequisites

​Set Up the Repo

​Scenario

​Trace the Attribution

​Find the Reason

​Investigate the Decision

​Read the Findings

​Troubleshooting

​Continue with

Search Past Agent Work

checkpoint Command Reference

Prerequisites

Set Up the Repo

Scenario

Trace the Attribution

Find the Reason

Investigate the Decision

Read the Findings

Troubleshooting

Continue with