Skip to content

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. It may begin with a cited failure whose trigger is unknown. fix carries an authorized, confirmed code defect through regression-first development. Neither a plausible explanation nor a passing test alone proves that the reported problem was corrected. A diagnosis is not permission to repair.

The work, from your side

Symptom → evidence → regression → handoff

Investigation is separate from implementation. Its five results can recommend a next action but cannot authorize it. This map is not a captured execution.

  1. You describe the failure

    Identify the symptom

    What you get
    Observed behavior, available expectation, evidence source, reproduction state, and any limits or unknown trigger.
    Before moving on
    Separate what happened from your suspected cause. A cited failure can support scoped investigation before replay succeeds.
    Check investigation entry
  2. codeArbiter investigates

    Compare the evidence

    What you get
    Plausible mechanisms with real discriminators and a cited CONFIRMED, REFUTED or INCONCLUSIVE assessment for each.
    Before moving on
    Check capture limits and source or runtime identity. The evidence sets the hypothesis count; no diagnostic edit or trial fix is implied.
    Inspect the debug contract
  3. The fix owner verifies a code defect

    See target red

    What you get
    A concrete regression obligation, an observed target failure, then the minimum correction and fresh passing result.
    Before moving on
    Confirm original caller authority. Reuse an adequate existing target-red test; an import or unrelated failure does not count.
    Inspect regression-first repair
  4. You inspect the result

    Keep the continuation in scope

    What you get
    The selected disposition, citations and limits, owner, authority needs, and next or resume action where applicable.
    Before moving on
    A debug result cannot start repair, mutate an ADR or board, merge a PR, or establish a release.
    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.

What you knowEntryExpected output
An identifiable symptom or cited failure has an unknown cause, even if its trigger is unknown
debug
One of five evidence-backed dispositions, including unresolved when a discriminator is blocked
A code defect is supported and repair is authorized
fix
An observed target-red regression before correction, then the remaining test-first gates
The behavior is as specified but the requirement is disputed
adr under its own attributed owner
An authorized decision, not an unapproved implementation change
You are asking how something works, with no defect
Ask a read-only question
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.

An active authorized fix may use one bounded internal diagnostic prerequisite and return to the same caller. That is not public command recursion. The debug result retains the original caller scope and cannot convert a diagnosis-only request into repair authority.

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.

Describe the affected checkout and current source revision, expected behavior where established, actual behavior, and the source of the reported failure. Record the action, input, environment, frequency, and recent changes where known. Name the reproduction state: reproduced, intermittent, not_yet_reproduced, unsafe_to_replay, or unavailable. Preserve a minimal failing input where it is safe to do so. A cited failure with an unknown trigger can enter scoped investigation as not_yet_reproduced; neither a failed replay nor missing trigger disproves it.

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 limit dependent action; they are not a reason to invent a log path or test command. Safe available reads may continue, with the gap reported. 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

Section titled “3. Inspect the hypothesis and evidence ledger”

The debug skill considers distinct plausible mechanisms and an observation that could distinguish each. There is no fixed hypothesis count. Ordinary environmental, configuration, or dependency explanations belong in the set when they fit the symptom, not to fill a quota. For each candidate, name what would confirm or refute it and where that evidence can be read. Before running a diagnostic action, assess its effects, resource bounds, and authority. Investigation does not edit source, add logging, refactor, or try a fix to test a suspicion.

Ledger fieldWhat you should receive
Hypothesis
A numbered mechanism, such as H1, rather than a restatement of the symptom
Confirm and refute signals
Observations that could actually distinguish that mechanism from alternatives
Citation
The relevant file and revision, log and time, or trace identifier
Result
CONFIRMED, REFUTED or INCONCLUSIVE, with the reason
Missing evidence
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. Compare evidence against its capture range and source or runtime identity before treating it as current. Preserve multiple supported contributors. If a new safe discriminator is available, gather it; otherwise return unresolved with the missing discriminator, next action, and resume condition. Missing diagnostic access is not a design question. Uncertainty cannot become a confirmed cause or no-action conclusion by repetition.

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.

The investigation returns exactly one disposition for the case. That does not force one physical cause; several supported contributors can remain distinct in the evidence ledger.

DispositionEvidence and continuation
confirmed_code_defect
A supported code cause, current expectation, cited trace or reproduction, and a concrete regression obligation. Recommend fix; the fix owner checks original caller authority and observes target red before repair. Debug does not pre-write the test.
confirmed_noncode_cause
A supported operational, environmental, external, or deployed-configuration cause. Name its existing owner or say none is known, and retain any permission blocker. Do not force a source patch.
design_question
Specific conflicting expectations and the decision they require. An ADR is optional and needs its own attributed owner; debug does not create one.
no_action
Positive evidence that behavior is required by the applicable contract or already resolved in the applicable state, with no remaining work in scope. Non-reproduction alone is insufficient. Close without a default board write or other state change.
unresolved
Established facts, the missing discriminator or prerequisite, blocked checks, next action, owner when known, and a resume condition. Do not invent a fix, ADR, or no-action verdict.

For a transient handoff packet, resolve the private debug-handoff.py validator from the loaded installed package, then send at most 65,536 UTF-8 bytes through stdin and close it. Invoke Python with -B, the absolute helper path, and literal validate once. Only exit 0 with valid: true and no errors permits packet transfer. A rejection or missing helper blocks validated transfer; do not retry a refusal through another interpreter. Validation checks packet structure, not evidence truth, freshness, or authority. The receiving owner rechecks applicability and the original caller scope. A separately authorized concrete task follow-up belongs to the existing task owner and installed writer. The debug result itself does not write the board.

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

5. Verify the regression and minimum correction

Section titled “5. Verify the regression and minimum correction”

Under the original caller’s repair authority, the fix owner checks the current causal evidence, names the responsible code path, and maps the bug-origin obligation into the existing TDD ledger. Compare the obligation with existing tests first. Reuse an adequate named test if it already fails on the broken source for the target reason; add a test only for an uncovered obligation. Observe that target red before correction. A missing module, syntax error, unrelated failure, test that never exercises the affected behavior, or merely proposed test cannot stand in for the reported defect. A material fixture or setup change requires renewed target red on the broken implementation.

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.

Ask for the disposition, observed symptom and expectation, reproduction state and limits, supported and inconclusive causes, evidence citations, relevant source and runtime binding, owner, authority needs, and next or resume action. For an authorized repair, also ask for the target-red test identity and failure, changed paths, fresh passing checks with their scope, and remaining findings. A result on one environment is not proof for every supported platform.

Use Review and ship a change for commit, PR and merge boundaries. Ordinary authorized repair uses the current source and applicable checks, including actual commit and merge permissions when delivery is requested. An explicit attestation claim separately needs supported host authority and current evidence. A debug summary or passing local regression does not create those receipts.

ObservationNext safe action
Cited failure with an unknown trigger
Start scoped safe investigation as not_yet_reproduced; keep the trigger unknown and seek a useful discriminator
No safe useful discriminator or required access
Return unresolved with the blocker, next action, and resume condition
Evidence would require changing instrumentation
Keep the diagnosis boundary explicit and scope the needed change separately
The test fails for an unrelated reason
Repair the test setup, then demonstrate the defect before writing fix code
A proposed fix changes an agreed behavior
Surface the requirement or decision instead of relabelling it a bug
The assertion was weakened to make green
Restore the behavioral obligation and correct the implementation
Work is interrupted or authority is stale
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.