# Evidence-First Protocol

`llmdebug` is an evidence transport and retry-state scaffold, not a replacement reasoner.
The LLM does the debugging logic; the tooling should keep evidence compact, structured,
and minimally biased.

## Core Principles

1. Evidence tools default to structured JSON (`response_format="json"`).
2. RCA coaching/state is explicit opt-in (`with_rca=true`), not default.
3. Heavy payloads are opt-in (`evidence_schema="full"`); summary mode remains compact.
4. Retry loops are delta-first: compare current failure to previous failure before patching.
5. Repeated failure signatures require new evidence before proposing another equivalent patch.

## Eval Packaging Conditions

- `traceback_only`: baseline pytest-only context.
- `with_snapshot`: traceback + snapshot baseline packaging.
- `with_snapshot_structured`: traceback + snapshot with structured evidence packaging and
  hard retry gate (`new evidence before same-signature patch`).

## Retry Gate Policy

When failure signatures repeat:

1. Compute a deterministic evidence fingerprint from retrieved evidence blocks.
2. If fingerprint is unchanged, do not propose a patch.
3. Record `note="retry_gate_no_new_evidence"` and retry-gate metadata.
4. Allow patch proposal only after evidence changes.

This policy keeps loops informative without adding model-side heuristics.
