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.
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.
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.
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.
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.
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
Section titled “1. Choose investigation or repair”| What you know | Entry | Expected 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.
2. Supply the symptom, not just a theory
Section titled “2. Supply the symptom, not just a theory”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 field | What 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.
4. Review the named result
Section titled “4. Review the named result”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.
| Disposition | Evidence 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.
6. Hand off what is actually proved
Section titled “6. Hand off what is actually proved”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.
When to stop or resume
Section titled “When to stop or resume”| Observation | Next 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.