Preview 0.33

U05: Investigate before changing code

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.

Why

The exercise depends on the released spike contract, not an Academy substitute command.

Expected result

You know which plugin is loaded and can locate debug, spike, commit, and conflict.

If that does not happen

If your host is older or does not expose the command, update the integration or stop; do not imitate its output by hand.

Evidence

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.

Why

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

Expected result

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 that does not happen

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.

Evidence

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.

Why

The bounded observation makes the real debug question reproducible without a fabricated transcript.

Expected result

You can state the observed behavior, reproduction boundary, expected no-action disposition, and spike question. Next safe step: run host-native debug.

If that does not happen

If the observation is absent or differs from the prepared fixture, stop and preserve the attempt; do not rewrite it.

Evidence

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.

Why

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

Expected result

A source-backed conclusion and unchanged worktree.

If that does not happen

If the investigation is unresolved, retain that uncertainty. Do not force a no-action conclusion or write a task automatically.

Evidence

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.

Why

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

Expected result

No board diff or pending changes.

If that does not happen

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.

Evidence

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.

Why

$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

Expected result

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 that does not happen

If code, a merge, or a pull request is proposed, stop; a spike has no implementation, merge, or PR exit.

Evidence

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.

Why

$ca-spike stops for user confirmation before it creates the disposable branch or explores.

Expected result

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 that does not happen

If the question, branch, or timebox differs, decline and correct the prompt; do not let a spike start from an unconfirmed or broadened question.

Evidence

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.

Why

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

Expected result

Only .codearbiter/spikes/u05-cache-key.md is now unstaged on the parent branch. Next safe step: review that one-file diff.

If that does not happen

If Git reports the spike ref is unavailable, preserve the state and stop; do not recreate findings or copy any spike code by hand.

Evidence

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.

Why

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

Expected result

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 that does not happen

If any code or extra path is staged, unstage it and preserve the evidence; do not use a broad add command.

Evidence

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.

Why

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

Expected result

One clean parent-branch commit changes only .codearbiter/spikes/u05-cache-key.md. Next safe step: delete the disposable branch.

If that does not happen

If the gate blocks, keep the parent and spike state intact until its finding is resolved; do not merge the spike branch.

Evidence

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.

Why

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

Expected result

Only the confirmed disposable branch is deleted.

If that does not happen

If the branch still contains unreviewed findings, stop before deletion; never merge it merely to make ordinary branch deletion succeed.

Evidence

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.

Why

Conflict is a human decision protocol, not an artifact generator.

Expected result

Work remains stopped until the person resolves the hierarchy conflict. Next safe step: resume only from the explicit resolution.

If that does not happen

Do not paraphrase a resolution or continue speculatively; present the actual sources and wait.

Evidence

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.

Why

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

Expected result

The preserved board and findings-only commit pass.

If that does not happen

Read the failed predicate, then return to the named boundary. Do not manufacture a transcript, receipt, or retained spike branch to force acceptance.

Evidence

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.

Why

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

Expected result

The failed attempt remains available.

If that does not happen

If Reset refuses because the attempt contains state it must preserve, archive that state first and follow the refusal guidance.

Evidence

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.

Next step

Continue with U06-preview-and-advanced-surfaces.

Recovery guidance