U05: Investigate before changing code
Choose the commands you use
Operating system
codeArbiter host
Know before you begin
Use debug when the cause is unknown. Use a spike for a short experiment that answers one design or implementation question. Investigation does not silently authorize a production change.
confirm the released command boundary
You · Browser · All operating systems
Run host Doctor and check the installed command catalog. This lesson follows the current read-only debug no-action contract; it does not require the old 2.15.1/0.7.2/0.8.1 cohort.
The exercise depends on the released spike contract, not an Academy substitute command.
You know which plugin is loaded and can locate debug, spike, commit, and conflict.
If your host is older or does not expose the command, update the integration or stop; do not imitate its output by hand.
Current installed commands.
What you will prove
Investigate the fictional cache-key observation. A current no-action debug exit returns a cited explanation and leaves the board and source unchanged.
Then bring only the spike's findings file back to the Academy branch in one commit. Confirm deletion of the disposable spike only after preserving its answer.
Prepare safely
prepare the bounded attempt
Run Academy Prepare from the clean training repository. It creates the U05 attempt branch and commits the observation fixture without changing the task board.
Prepare supplies a reproducible input, not a simulated debug or spike result.
Academy · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare U05-debug-spike-conflict
Academy · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U05-debug-spike-conflict
Academy · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U05-debug-spike-conflict
Academy creates a clean U05 attempt on academy/U05-debug-spike-conflict/1 with the committed observation and scenario files. Next safe step: read the observation.
If Prepare refuses because the repository is dirty or a prior attempt exists, preserve that state, use Reset only after reviewing it, then retry Prepare.
Prepare output, the new attempt branch, its preparation commit, and a clean worktree.
read the prepared cache-key observation
You · Active codeArbiter harness · All operating systems
Read docs/U05-cache-key-observation.md before invoking a host command. It is a fictional Academy input, never output from $ca-debug or $ca-spike.
The bounded observation makes the real debug question reproducible without a fabricated transcript.
You can state the observed behavior, reproduction boundary, expected no-action disposition, and spike question. Next safe step: run host-native debug.
If the observation is absent or differs from the prepared fixture, stop and preserve the attempt; do not rewrite it.
The committed prepared observation, with no debug.note receipt in it.
The prepared observation is input to investigate, not a transcript or a conclusion you may rewrite to make the lesson pass.
Practice
run debug without code changes
Investigate the prepared observation. A current no-action exit returns a cited explanation without writing a task, report, or production change.
A no-action result explains source evidence without inventing work.
Your agent · Claude Code harness · All operating systems
/ca:debug U05 cache-key observation
Your agent · Codex harness · All operating systems
$ca-debug U05 cache-key observation
Your agent · Pi harness · All operating systems
/ca-debug U05 cache-key observation
Your agent · Pi harness · All operating systems
/skill:ca-debug U05 cache-key observation
A source-backed conclusion and unchanged worktree.
If the investigation is unresolved, retain that uncertainty. Do not force a no-action conclusion or write a task automatically.
Observe the explanation in the session; Check cannot authenticate the conversation.
Confirm debug left the repository unchanged
Inspect status and the board diff. Both should be unchanged. Do not manufacture a debug.note entry.
The board is durable plugin output; reviewing it prevents unrelated changes from being committed as debug evidence.
You · Native terminal · Windows
git status --short --untracked-files=all
git diff -- .codearbiter/open-tasks.md
git diff --check
You · Native terminal · macOS
git status --short --untracked-files=all
git diff -- .codearbiter/open-tasks.md
git diff --check
You · Native terminal · Linux
git status --short --untracked-files=all
git diff -- .codearbiter/open-tasks.md
git diff --check
No board diff or pending changes.
If any pending change or board entry appears, stop and preserve the status and diff. Investigate why the read-only debug step changed the repository before continuing; do not manufacture a task or receipt.
The prepared board is preserved.
Read the cited evidence. A no-action conclusion needs a positive reason; an unsuccessful attempt to reproduce a reported problem is not enough.
run the disposable spike
Use the host-native spike command with the fixture question U05 cache key. Work only on spike/u05-cache-key and commit only its findings file there.
$ca-spike discards implementation while preserving a bounded answer.
Your agent · Claude Code harness · All operating systems
/ca:spike U05 cache key
Your agent · Codex harness · All operating systems
$ca-spike U05 cache key
Your agent · Pi harness · All operating systems
/ca-spike U05 cache key
Your agent · Pi harness · All operating systems
/skill:ca-spike U05 cache key
The host restates the bounded U05 cache-key question and pauses before creating spike/u05-cache-key. Next safe step: confirm that exact question.
If code, a merge, or a pull request is proposed, stop; a spike has no implementation, merge, or PR exit.
The prompt is transient. The durable evidence is the committed findings file restored to the parent; the spike branch must be absent at Check.
confirm the spike question
You · Active codeArbiter harness · All operating systems
When the host restates U05 cache key and asks for confirmation, confirm only if it is the bounded fixture question and the branch is spike/u05-cache-key.
$ca-spike stops for user confirmation before it creates the disposable branch or explores.
The confirmed host flow creates spike/u05-cache-key and on its answered exit commits only .codearbiter/spikes/u05-cache-key.md. Next safe step: restore only that findings file to the parent.
If the question, branch, or timebox differs, decline and correct the prompt; do not let a spike start from an unconfirmed or broadened question.
The prompt is not Check evidence; the findings-only commit and absent branch are observable evidence.
restore only the committed findings
Return to the Academy attempt branch and restore only the committed finding from spike/u05-cache-key. This is a native Git transfer, not a merge.
The released spike contract permits the finding's contents to cross back but forbids the spike commit and exploratory code.
You · Native terminal · Windows
git restore --source spike/u05-cache-key -- .codearbiter/spikes/u05-cache-key.md
You · Native terminal · macOS
git restore --source spike/u05-cache-key -- .codearbiter/spikes/u05-cache-key.md
You · Native terminal · Linux
git restore --source spike/u05-cache-key -- .codearbiter/spikes/u05-cache-key.md
Only .codearbiter/spikes/u05-cache-key.md is now unstaged on the parent branch. Next safe step: review that one-file diff.
If Git reports the spike ref is unavailable, preserve the state and stop; do not recreate findings or copy any spike code by hand.
An unstaged parent diff limited to the one findings file.
review the findings-only transfer
Inspect the parent diff and stage exactly .codearbiter/spikes/u05-cache-key.md, then inspect the cached diff before committing.
Staging and cached-diff review make the one-file transfer boundary visible before the commit gate runs.
You · Native terminal · Windows
git add -- .codearbiter/spikes/u05-cache-key.md
git diff --cached --name-only
git diff --cached -- .codearbiter/spikes/u05-cache-key.md
You · Native terminal · macOS
git add -- .codearbiter/spikes/u05-cache-key.md
git diff --cached --name-only
git diff --cached -- .codearbiter/spikes/u05-cache-key.md
You · Native terminal · Linux
git add -- .codearbiter/spikes/u05-cache-key.md
git diff --cached --name-only
git diff --cached -- .codearbiter/spikes/u05-cache-key.md
The cached path list contains only .codearbiter/spikes/u05-cache-key.md with all four findings headings. Next safe step: commit the parent transfer through the host.
If any code or extra path is staged, unstage it and preserve the evidence; do not use a broad add command.
Cached diff and path list for exactly the one findings file.
commit the parent findings transfer
Use the host-native commit gate to commit the reviewed parent findings transfer by itself.
The parent commit is distinct from the disposable spike commit and preserves only the answer.
Your agent · Claude Code harness · All operating systems
/ca:commit
Your agent · Codex harness · All operating systems
$ca-commit
Your agent · Pi harness · All operating systems
/ca-commit
Your agent · Pi harness · All operating systems
/skill:ca-commit
One clean parent-branch commit changes only .codearbiter/spikes/u05-cache-key.md. Next safe step: delete the disposable branch.
If the gate blocks, keep the parent and spike state intact until its finding is resolved; do not merge the spike branch.
A clean parent worktree and a distinct one-file findings commit.
delete the unmerged disposable branch
Review the committed parent findings, confirm deletion of only spike/u05-cache-key, then run this card. If the agent performs deletion, give it explicit confirmation first.
The branch is disposable by contract, and Git correctly treats its unmerged exploratory commit as not merged.
You · Native terminal · Windows
git branch -D spike/u05-cache-key
You · Native terminal · macOS
git branch -D spike/u05-cache-key
You · Native terminal · Linux
git branch -D spike/u05-cache-key
Only the confirmed disposable branch is deleted.
If the branch still contains unreviewed findings, stop before deletion; never merge it merely to make ordinary branch deletion succeed.
The parent retains the findings.
The findings-only transfer does not merge the spike. The deletion uses git branch -D because that exploratory commit remains unmerged. Confirm the exact branch and the preserved answer before running it.
honor the conflict stop
You · Active codeArbiter harness · All operating systems
If conflicting rules appear, use $ca-conflict to present exact sources and wait for the user's resolution before any further work.
Conflict is a human decision protocol, not an artifact generator.
Work remains stopped until the person resolves the hierarchy conflict. Next safe step: resume only from the explicit resolution.
Do not paraphrase a resolution or continue speculatively; present the actual sources and wait.
Human acknowledgement is outside automated Check; no fake conflict receipt exists.
Use conflict when actual sources disagree. Do not invent a conflict or a resolution receipt to finish the exercise.
Recognize success
The task board matches Prepare. One new parent commit contains only .codearbiter/spikes/u05-cache-key.md, with Question, What tried, Answer, and Implication sections. The disposable spike ref is absent and the worktree is clean.
Check
check the accepted repository state
Run Check after the findings-only parent commit is clean and the confirmed disposable branch is deleted.
Check evaluates durable repository facts, never an alleged host invocation or conflict decision.
Academy · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check U05-debug-spike-conflict
Academy · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" check U05-debug-spike-conflict
Academy · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" check U05-debug-spike-conflict
The preserved board and findings-only commit pass.
Read the failed predicate, then return to the named boundary. Do not manufacture a transcript, receipt, or retained spike branch to force acceptance.
Repository state, not debug invocation or deletion approval.
Check observes the prepared input, preserved board, findings, commit boundary, and missing spike ref. It cannot prove debug invocation, reasoning quality, or deletion approval.
Recover or continue
reset a failed attempt before retrying
Use Reset for a fresh numbered attempt after preserving failed evidence. It is not permission to discard work.
A failed experiment should be recoverable without inventing or manually deleting evidence.
Academy · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset U05-debug-spike-conflict
Academy · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U05-debug-spike-conflict
Academy · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U05-debug-spike-conflict
The failed attempt remains available.
If Reset refuses because the attempt contains state it must preserve, archive that state first and follow the refusal guidance.
Preserved history and a fresh baseline.
Hint 1. A debug conclusion does not create a task by default.
Hint 2. Transfer the findings file, never exploratory code or the spike commit.
Hint 3. If rules conflict, preserve the state and wait for the actual user's resolution. A passing Check is not that decision.
Understand the mechanism
Investigation reduces uncertainty. A spike leaves an answer that guides later production work through the proper feature or fix workflow. Return to a Project and Investigate and Fix a Defect cover choosing the next lane.
Use this in your own project. Give debug the observed behavior, expected behavior, and evidence. Give a spike one question and a stopping condition. Take a confirmed bug's reproduction into the fix lane.