Investigate and Fix a Defect

Use this guide when your application’s behavior is wrong. If codeArbiter itself is dormant, a hook fails to load, or a host cannot find its package, begin with installation troubleshooting instead.

debug investigates an unknown cause without changing application code. fix carries a confirmed defect through regression-first development. Neither a plausible explanation nor a passing test alone proves that the reported problem was corrected.

The work, from your side

Symptom → evidence → regression → handoff

Investigation is separate from implementation. A design ambiguity or justified no-action close is a valid alternative to fixing code. The map is not a captured execution.

1. 01

   You describe the failure

   Make it reproducible

   What you get

   Observed and expected behavior, the input and environment, and a minimal repro or intermittent trigger.

   Before moving on

   Separate what happened from your suspected cause. Missing facts must stay visible.

   Check investigation entry →
2. 02

   codeArbiter investigates

   Compare the evidence

   What you get

   At least three distinct hypotheses and a cited CONFIRMED, REFUTED or INCONCLUSIVE assessment for each.

   Before moving on

   Require confirming and refuting signals. Reading evidence does not permit instrumentation edits or a trial fix.

   Inspect the debug contract →
3. 03

   The fix lane verifies the defect

   See the regression fail

   What you get

   A named test tied to the reproduction, its expected failure, then the minimum correction and passing result.

   Before moving on

   An import failure is not the defect. Keep the assertion intact between red and green.

   Inspect regression-first repair →
4. 04

   You inspect the handoff

   Separate fixed from shipped

   What you get

   Changed paths, current test and review results, remaining uncertainty and the next delivery action.

   Before moving on

   Local green is not a merged PR or a release. Preserve the applicable host-authority and delivery boundaries.

   Review and deliver the correction →

Reading map, not a captured run or live status. Only the actual artifacts, approvals and fresh checks establish what has completed.

1. Choose investigation or repair

What you know	Entry	Expected output
What you know The symptom is reproducible but the cause is unknown	Entry debug	Expected output A diagnosis with cited evidence and exactly one named exit
What you know The bug and regression obligation are already known	Entry fix	Expected output A failing regression before correction, then the remaining test-first gates
What you know The behavior is as specified but the requirement is disputed	Entry adr	Expected output An attributed decision, not an unapproved implementation change
What you know You are asking how something works, with no defect	Entry Ask a read-only question	Expected output An explanation rather than a repair lane

In Claude Code the entries are /ca:debug and /ca:fix; Codex uses $ca-debug and $ca-fix; Pi uses /ca-debug and /ca-fix. Enter them in the coding host, not the native terminal. Include the symptom or confirmed bug after the entry. A supported spelling does not prove that every advanced capability is available in your installed adapter.

For a specifically requested one-time inspection tool, use the bounded dependency path. Temporary use still requires a pinned command and confirmation; adopting a tool is a different decision.

2. Supply the symptom, not just a theory

Describe the affected checkout and current source revision, expected behavior, actual behavior, exact action and input, environment, frequency, and recent changes. Preserve a minimal failing input where it is safe to do so. For an intermittent problem, record its trigger conditions and both failing and successful observations instead of claiming it happens every time.

A useful request could read:

Illustrative request, not a captured run:
Exporting one saved search returns no CSV.
Expected: a header and one data row.
Input: name Open, query state:open.
It repeats in this checkout and test runtime.
Investigate the cause before changing code.

Use git rev-parse --show-toplevel, git branch --show-current, git status --short, and git rev-parse HEAD in the native terminal to identify the checkout, branch, changed paths and commit. These commands do not establish what the application did; pair them with the actual error or result. Preserve unrelated changes.

The investigation reads .codearbiter/tech-stack.md for log locations, trace tools and runner conventions, and CONTEXT.md for domain and stage. Missing entries are a request for information, not a reason to invent a log path or test command. Review security controls when the failure crosses an authentication, cryptographic or other security boundary.

Before sharing diagnostics, redact tokens, credentials, personal data, private URLs and sensitive payloads. Keep the error class, relevant time, source revision and a safe correlation identifier so the evidence still explains the failure. Do not dump all environment variables.

3. Inspect the hypothesis and evidence ledger

The debug skill considers at least three distinct mechanisms, including an ordinary environmental, configuration or dependency explanation. For each, it names what would confirm it, what would refute it, and where that evidence can be read. Investigation does not edit source, add logging, refactor or try a fix to test a suspicion.

Ledger field	What you should receive
Ledger field Hypothesis	What you should receive A numbered mechanism, such as H1, rather than a restatement of the symptom
Ledger field Confirm and refute signals	What you should receive Observations that could actually distinguish that mechanism from alternatives
Ledger field Citation	What you should receive The relevant file and revision, log and time, or trace identifier
Ledger field Result	What you should receive CONFIRMED, REFUTED or INCONCLUSIVE, with the reason
Ledger field Missing evidence	What you should receive The specific observation still needed and its owner or location

INCONCLUSIVE remains INCONCLUSIVE. The absence of an error in an incomplete log is not proof that a subsystem worked. If every hypothesis remains inconclusive, the lane returns to evidence gathering or surfaces the unresolved behavior/decision through the ambiguity exit. It cannot silently convert uncertainty into a confirmed bug or a no-action conclusion.

The summary is an output of the investigation. The contract does not promise a new, fixed-path debug.md report or a dedicated persisted evidence-ledger file. Retain the actual summary and citations needed for the next handoff rather than assuming that a conversation created a file.

4. Review the named exit

A confirmed bug routes to fix with its hypothesis, evidence and a named regression-test obligation. That obligation must reproduce the original condition. Debug does not pre-write the test; the fix lane owns that work.

A behavior or design ambiguity carries the disputed requirement and evidence into adr. Authorship requires your attribution. Accepting a decision does not prove its implementation or verification; follow Record an architecture decision.

A no-action close requires a cited rationale, such as a demonstrated environmental event or an independently identified correction. This exit records a queued board note through the task helper so the symptom can be revisited. It does not edit application code, but it is not a zero-write operation: the board entry affects in-flight counts. Do not mark it complete merely because this investigation needs no code change.

Out-of-scope findings remain [NEEDS-TRIAGE] items. They are not permission to expand the fix.

5. Verify the regression and minimum correction

The fix path reproduces the bug, names the responsible code path, writes a regression, and checks that it fails for the right reason. Review that failure before the correction. A missing module, syntax error, test that never executes the affected behavior, or test that already passes cannot stand in for the reported defect.

The minimum correction then makes the same assertion pass. The test-first skill checks mapped obligations, relevant existing tests, the project’s coverage requirements, lint and type checks. Commands and thresholds come from project context; a missing coverage tool needs the documented no-tooling treatment, not an invented percentage or a silent pass.

The saved-search example provides bounded local evidence to inspect: its baseline returns None, including for non-empty input. The tests require CSV text for non-empty input. The recorded result shows two assertion failures against that baseline and all three tests passing against the completed serializer. The initial failure is the missing CSV result, not a demonstrated quoting-only defect. These fixtures are not a recorded debug session, an installed-host run, or evidence about your own application.

6. Hand off what is actually proved

Ask for the original reproduction, confirmed cause and citations, regression name and failure, changed paths, fresh passing checks with their scope, remaining findings, and the next action. Keep the selected source identity visible. A result on one environment is not proof for every supported platform.

Use Review and ship a change for commit, PR and merge boundaries. Existing typed work still needs its supported host authority and current acceptance evidence. A debug summary or passing local regression does not create those receipts.

When to stop or resume

Observation	Next safe action
Observation No repeatable repro or intermittent-trigger profile	Next safe action Ask for the missing input, state or timing evidence before choosing a cause
Observation Evidence would require changing instrumentation	Next safe action Keep the diagnosis boundary explicit and scope the needed change separately
Observation The test fails for an unrelated reason	Next safe action Repair the test setup, then demonstrate the defect before writing fix code
Observation A proposed fix changes an agreed behavior	Next safe action Surface the requirement or decision instead of relabelling it a bug
Observation The assertion was weakened to make green	Next safe action Restore the behavioral obligation and correct the implementation
Observation Work is interrupted or authority is stale	Next safe action Preserve the summary, branch and current evidence; follow Resume and recover

A rollback is a reviewed change too. Agree which correction is being undone and what behavior must be restored; do not reset unrelated work, discard learner records or delete evidence to make a failed attempt disappear. The exact contracts remain in debug, fix and test-first development.