# 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. Evidence blocks are assigned stable `evidence_id`s and deduplicated across retries.
6. Prompt budgets are deterministic and section-aware (retry packet, logs, snapshot, evidence).
7. 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`), plus delta-only retries
  after attempt 1.

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

## Prompt Budgeting

Stage-B prompt assembly uses deterministic budgets:

1. Per-section caps for retry packet, pytest output, snapshot summary, and Stage-A evidence.
2. Optional total prompt cap with deterministic truncation/drop order.
3. Attempt metadata records budget usage and dropped sections for analysis.

## Reporting

Analyzer outputs include:

1. Legacy uplift (`with_snapshot - traceback_only`) for continuity.
2. Structured uplift metrics and retry-gate block rate.
3. Pairwise uplift matrix across all observed conditions.
4. Prompt-size and evidence-ID telemetry for protocol-level debugging.
