Skip to content
codeArbitercodeArbiter

Debug, spike, and conflict without inventing evidence

Know before you begin

Section titled “Know before you begin”

This lesson uses the released codeArbiter contract. The website gives the sequence and your host runs the real commands. Academy can inspect repository facts at the end, but it cannot prove an agent’s private reasoning or a human conflict decision.

  1. YouBrowser

    confirm the released command boundary

    Confirm that your host has codeArbiter 2.15.1 for Claude, ca-codex 0.7.2 for Codex, or ca-pi 0.8.1 for Pi. U05 uses only real $ca-debug, $ca-spike, $ca-commit, and $ca-conflict behavior.

    Why this matters: The exercise depends on the released spike contract, not an Academy substitute command.

    Expected result

    You know which host command to use and that a spike never merges or opens a pull request. Next safe step: Prepare the bounded attempt.

    Evidence

    Your host integration version and the public U05 lesson boundary.

    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.

What you will prove

Section titled “What you will prove”

You will preserve two real outputs. The debug no-action exit records its cited conclusion through taskwrite; its optional debug.note ID is not evidence. The spike preserves only its four-part findings file on the parent branch, then deletes the exploratory branch. Neither output proves a command transcript or invents a conflict receipt.

Prepare safely

Section titled “Prepare safely”

  1. Academy

    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 this matters: Prepare supplies a reproducible input, not a simulated debug or spike result.

    Windows

    $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.32\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare U05-debug-spike-conflict

    macOS

    academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U05-debug-spike-conflict

    Linux

    academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/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.

    Evidence

    Prepare output, the new attempt branch, its preparation commit, and a clean worktree.

    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.

  1. YouActive harness

    read the prepared cache-key observation

    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 this matters: 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.

    Evidence

    The committed prepared observation, with no debug.note receipt in it.

    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.

Practice

Section titled “Practice”

Keep the parent attempt clean between the two commits. The commands below state which surface owns each action and what evidence must remain afterward.

Debug: preserve the no-action close

Section titled “Debug: preserve the no-action close”

  1. Your host

    run debug without code changes

    Run the host-native debug command on the prepared cache-key observation and take its no-action exit. Do not write a debug report or modify product code.

    Why this matters: $ca-debug owns the investigation and its real no-action exit writes the board only through taskwrite.py.

    Any OS · Claude Code

    /ca:debug U05 cache-key observation

    Any OS · Codex

    $ca-debug U05 cache-key observation

    Any OS · Pi

    /ca-debug U05 cache-key observation

    Any OS · Pi

    /skill:ca-debug U05 cache-key observation

    Expected result

    The no-action exit queues one taskwrite-written U05 cache-key entry with a Desc: rationale and makes no code change. Its dotted ID is optional. Next safe step: review only the board diff.

    Evidence

    An unstaged taskwrite-shaped .codearbiter/open-tasks.md entry with Desc:, not a transcript.

    If that does not happen

    If the diagnosis selects fix or ADR, stop; this bounded exercise requires the declared no-action exit.

  1. You

    review the debug-board boundary

    Inspect the board diff and confirm it contains only the taskwrite-written U05 cache-key entry with its Desc: continuation; a dotted debug.note ID is optional.

    Why this matters: The board is durable plugin output; reviewing it prevents unrelated changes from being committed as debug evidence.

    Windows

    git diff -- .codearbiter/open-tasks.md
git diff --check

    macOS

    git diff -- .codearbiter/open-tasks.md
git diff --check

    Linux

    git diff -- .codearbiter/open-tasks.md
git diff --check

    Expected result

    The only intended diff is the cited taskwrite-written U05 cache-key board entry with Desc:, and git diff --check is silent. Next safe step: commit the board through the host.

    Evidence

    Reviewed unstaged taskwrite-shaped diff limited to .codearbiter/open-tasks.md.

    If that does not happen

    If other paths or an entry without taskwrite's Desc: form appear, stop and preserve the diff; do not edit a receipt to imitate taskwrite.

  1. Your host

    commit the no-action board entry

    Use the host-native commit gate to commit the reviewed debug board entry by itself.

    Why this matters: $ca-commit is the sanctioned commit path and keeps the debug close distinct from the later spike finding.

    Any OS · Claude Code

    /ca:commit

    Any OS · Codex

    $ca-commit

    Any OS · Pi

    /ca-commit

    Any OS · Pi

    /skill:ca-commit

    Expected result

    One clean parent-branch commit changes only .codearbiter/open-tasks.md. Next safe step: run the disposable spike.

    Evidence

    A committed taskwrite-shaped board change and a clean worktree.

    If that does not happen

    If the gate blocks, preserve its findings and resolve them; do not fold the board entry into the findings commit.

The first parent commit contains only .codearbiter/open-tasks.md. Check verifies the resulting taskwrite-shaped U05 cache-key entry and clean tree, not a claimed command invocation or a fixed task ID.

Spike: transfer only the answer

Section titled “Spike: transfer only the answer”

  1. Your host

    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 this matters: $ca-spike discards implementation while preserving a bounded answer.

    Any OS · Claude Code

    /ca:spike U05 cache key

    Any OS · Codex

    $ca-spike U05 cache key

    Any OS · Pi

    /ca-spike U05 cache key

    Any OS · Pi

    /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.

    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.

    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.

  1. YouActive harness

    confirm the spike question

    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 this matters: $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.

    Evidence

    The prompt is not Check evidence; the findings-only commit and absent branch are observable evidence.

    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.

  1. You

    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 this matters: The released spike contract permits the finding�s contents to cross back but forbids the spike commit and exploratory code.

    Windows

    git restore --source spike/u05-cache-key -- .codearbiter/spikes/u05-cache-key.md

    macOS

    git restore --source spike/u05-cache-key -- .codearbiter/spikes/u05-cache-key.md

    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.

    Evidence

    An unstaged parent diff limited to the one findings file.

    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.

  1. You

    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 this matters: Staging and cached-diff review make the one-file transfer boundary visible before the commit gate runs.

    Windows

    git add -- .codearbiter/spikes/u05-cache-key.md
git diff --cached --name-only
git diff --cached -- .codearbiter/spikes/u05-cache-key.md

    macOS

    git add -- .codearbiter/spikes/u05-cache-key.md
git diff --cached --name-only
git diff --cached -- .codearbiter/spikes/u05-cache-key.md

    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.

    Evidence

    Cached diff and path list for exactly the one findings file.

    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.

  1. Your host

    commit the parent findings transfer

    Use the host-native commit gate to commit the reviewed parent findings transfer by itself.

    Why this matters: The parent commit is distinct from the disposable spike commit and preserves only the answer.

    Any OS · Claude Code

    /ca:commit

    Any OS · Codex

    $ca-commit

    Any OS · Pi

    /ca-commit

    Any OS · Pi

    /skill:ca-commit

    Expected result

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

    Evidence

    A clean parent worktree and a distinct one-file findings commit.

    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.

  1. You

    delete the unmerged disposable branch

    After the parent findings commit is clean, delete the intentionally unmerged disposable spike branch. Force deletion is required because the findings-only restore did not merge its commit.

    Why this matters: The branch is disposable by contract, and Git correctly treats its unmerged exploratory commit as not merged.

    Windows

    git branch -D spike/u05-cache-key

    macOS

    git branch -D spike/u05-cache-key

    Linux

    git branch -D spike/u05-cache-key

    Expected result

    refs/heads/spike/u05-cache-key is absent while the committed parent findings file remains. Next safe step: use Check.

    Evidence

    Absent U05 spike ref and retained parent findings commit.

    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.

The native git branch -D is intentional. The findings-only restore leaves the disposable spike commit unmerged. Do not merge merely to make ordinary branch deletion succeed. The parent receives the findings file’s contents, never the spike commit or exploratory code.

Conflict: stop for a person

Section titled “Conflict: stop for a person”

  1. YouActive harness

    honor the conflict stop

    If conflicting rules appear, use $ca-conflict to present exact sources and wait for the user's resolution before any further work.

    Why this matters: 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.

    Evidence

    Human acknowledgement is outside automated Check; no fake conflict receipt exists.

    If that does not happen

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

Recognize success

Section titled “Recognize success”

Check accepts repository facts only: the exact prepared observation; a first parent commit containing the taskwrite-shaped no-action board entry; a second parent commit with only .codearbiter/spikes/u05-cache-key.md; and no spike/u05-cache-key ref. It rejects copied or uncommitted exploratory code. It cannot prove that a host command ran or that a person resolved a conflict wisely.

Check

Section titled “Check”

  1. Academy

    check the accepted repository state

    Run Academy Check after the board and findings commits are clean and the U05 spike branch is deleted.

    Why this matters: Check evaluates durable repository facts, never an alleged host invocation or conflict decision.

    Windows

    $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.32\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check U05-debug-spike-conflict

    macOS

    academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
"$academy" --repository "$PWD" check U05-debug-spike-conflict

    Linux

    academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
"$academy" --repository "$PWD" check U05-debug-spike-conflict

    Expected result

    Academy evaluates the prepared U05 attempt and accepts only the clean two-commit findings-only lifecycle. Next safe step: continue to U06.

    Evidence

    Check result plus the clean attempt, two parent commits, and absent U05 spike ref.

    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.

Recover or continue

Section titled “Recover or continue”

  1. Academy

    reset a failed attempt before retrying

    Use Academy Reset only when you need to discard this practice attempt and prepare it again. Reset returns the repository to its pre-U05 branch state.

    Why this matters: A failed experiment should be recoverable without inventing or manually deleting evidence.

    Windows

    $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.32\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset U05-debug-spike-conflict

    macOS

    academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U05-debug-spike-conflict

    Linux

    academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U05-debug-spike-conflict

    Expected result

    Academy removes the U05 attempt branch and restores the original branch without altering unrelated work. Next safe step: Prepare a new attempt.

    Evidence

    Reset output, restored original branch, and preserved unrelated repository state.

    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.

Never merge or open a pull request for a spike branch, copy spike code to the parent, or keep a spike branch merely to satisfy Check. If $ca-conflict fires, stop work and wait for the user’s resolution before continuing.

Hint 1

Section titled “Hint 1”

Read the prepared observation before debugging. It is an input to investigate, not a transcript that you can edit into evidence.

Hint 2

Section titled “Hint 2”

The parent board commit and parent findings commit are intentionally separate. Check rejects a single commit that combines them.

Hint 3

Section titled “Hint 3”

git branch -D is correct only after the parent has committed the restored findings file. It deletes the intentionally unmerged disposable branch; it does not merge it.

Understand the mechanism

Section titled “Understand the mechanism”

Prepare commits the fictional observation so every learner begins from the same bounded question. The host owns debug and spike behavior. Academy Check reads only the resulting Git range, task board, findings file, deleted U05 spike ref, and clean worktree. That is why a copied exploratory change, retained branch, invented receipt, or merged spike cannot pass.