Skip to content

Investigate before changing code

Read alongside this lesson: Return to a Project (guide) · Investigate and Fix a Defect (guide)

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.

  1. YouBrowser

    confirm the released command boundary

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

    Evidence

    Current installed commands.

    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.

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.

  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.33\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.33/bin/arbiter-academy"
    "$academy" --repository "$PWD" prepare U05-debug-spike-conflict

    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.

    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.

The prepared observation is input to investigate, not a transcript or a conclusion you may rewrite to make the lesson pass.

  1. Your host

    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 this matters: A no-action result explains source evidence without inventing work.

    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 · Fallback

    /skill:ca-debug U05 cache-key observation

    Expected result

    A source-backed conclusion and unchanged worktree.

    Evidence

    Observe the explanation in the session; Check cannot authenticate the conversation.

    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.

  1. You

    Confirm debug left the repository unchanged

    Inspect status and the board diff. Both should be unchanged. Do not manufacture a debug.note entry.

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

    Windows

    git status --short --untracked-files=all
    git diff -- .codearbiter/open-tasks.md
    git diff --check

    macOS

    git status --short --untracked-files=all
    git diff -- .codearbiter/open-tasks.md
    git diff --check

    Linux

    git status --short --untracked-files=all
    git diff -- .codearbiter/open-tasks.md
    git diff --check

    Expected result

    No board diff or pending changes.

    Evidence

    The prepared board is preserved.

    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.

Read the cited evidence. A no-action conclusion needs a positive reason; an unsuccessful attempt to reproduce a reported problem is not enough.

  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 · Fallback

    /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 · Fallback

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

    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

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

    Only the confirmed disposable branch is deleted.

    Evidence

    The parent retains the findings.

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

  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.

Use conflict when actual sources disagree. Do not invent a conflict or a resolution receipt to finish the exercise.

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.

  1. Academy

    check the accepted repository state

    Run Check after the findings-only parent commit is clean and the confirmed disposable 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.33\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.33/bin/arbiter-academy"
    "$academy" --repository "$PWD" check U05-debug-spike-conflict

    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.

    Evidence

    Repository state, not debug invocation or deletion approval.

    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.

Check observes the prepared input, preserved board, findings, commit boundary, and missing spike ref. It cannot prove debug invocation, reasoning quality, or deletion approval.

  1. Academy

    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 this matters: A failed experiment should be recoverable without inventing or manually deleting evidence.

    Windows

    $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\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.33/bin/arbiter-academy"
    "$academy" --repository "$PWD" reset U05-debug-spike-conflict

    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.

    Evidence

    Preserved history and a fresh baseline.

    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.

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.

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.