VianoBugAnalysis/docs/handoff-outcomes-v2.md

Differentiated remediation handoff v2

This user-approved extension separates a successful causal diagnosis from the kind of follow-up work needed. The architecture document remains unchanged. BugAnalysis diagnoses, describes missing implementation information and produces handoff documents. It does not execute remediation, coordinate recipients, monitor their work or enforce downstream dependencies or execution readiness.

Documents and statuses

For every confirmed diagnosis handled by the new handoff protocol, the package contains both:

• handoffs/coding/CR-NNNN/change_request.json (plus a readable summary). format_version=2, assignment=assigned|none, and a required human_dev_assigned boolean make the intent explicit. The request status is ready, template or none. None means no coding assignment was necessary or possible; the reason is retained. The JSON does not contain the human task body. It contains coding-relevant instructions, including missing input and named placeholder tokens when the task is to create a template.
• handoffs/human-dev/HD-NNNN/human_dev_request.md. This is prose with a task title, reason, instructions and expected result. It can request implementation data collection, completing templates, or an operational/admin correction. With no human task it explicitly says Kein Human-Dev-Auftrag vorhanden. The manifest points to this document through human_dev_request.

The generation decision is saved for provenance under analysis/change-requests/NNNN/decision.json; it contains the model's two assignments so both delivered documents can be reproduced and verified. The coding JSON only conveys whether a human also received an assignment.

A template order must name unique tokens such as {{POSITION_X}} and describe which data is absent. This describes the coding task; BugAnalysis neither checks the eventual implementation nor waits for anyone to fill those tokens. Assigned coding tasks retain known-reference, root-scope and validation-instruction checks. Verified project-research captures are usable as local implementation context. The service does not require canonical reference archives where human-selected, reviewed remediation data would suffice. Semantic correctness of task prose remains an LLM responsibility; the structural validator cannot infer every error.

Completion and responsibility

Ready coding, template coding, human-only and explicit no-assignment documents all follow BUILDING_DIAGNOSIS -> OUTPUT_READY -> HANDED_OFF (after recipient acknowledgement). A human remediation task is not a pending investigation request. No new waiting status, work queue, feedback requirement or dependency gate exists. Output validation checks the handoff package itself, including document hashes, manifest pointers and identity. It does not validate future recipient actions.

Missing repair data does not produce FAILED_TO_ANALYZE or BLOCKED. If handoff model responses repeatedly fail validation, a deterministic no-coding/human-dev assignment asks for external preparation of remediation instructions; the confirmed diagnosis remains successful. Model-provider failures can still block this internal document-production step. Diagnosis data collection and its existing asynchronous investigation workflow are unchanged. An inconclusive diagnosis still goes to review without a remediation coding task.

Versioning and replay

New handoff contexts freeze handoff_protocol=2. New calls now use change_request_v4 (compact v3 view with broader remediation-data guidance); already persisted v1/v2/v3 requests keep their original prompt, including crash recovery and provider retries. Persisted historical contexts and calls keep their original prompt/hash. Pending legacy responses are deterministically adapted into both new handoff documents; closed historical packages retain v1 output semantics, including old insufficient-context review packages. Closed historical case packages are not silently rewritten. A new trial can start from a pre-handoff generation in a separate workspace to exercise v2 without repeating the diagnosis or overwriting the original case.

Both documents and all original package files survive portable export and replay. No additional LLM phase is added, and research budgets are neither reset nor spent by handoff document generation.

Compact handoff requests and correction feedback

The complete frozen context stays in the package. The v3 model view retains the accepted diagnosis (including uncertainty), full interpretation, original human observations, bug description, expected behavior and data-quality qualifiers. Every investigation evidence payload remains complete, including query filters, row coverage, truncation indicators and snapshot origin. Evidence record history is replaced in the request by its content reference and hash; it remains in the full context. Raw input inventories, runtime fact catalogs and duplicate source catalogs are omitted at this post-diagnosis stage. No LLM summary is generated. The output schema remains in the model message as well as the gateway contract, so JSON-object and text-only endpoints still receive the complete output contract.

local_context offers only exact source/evidence pairs accepted by the existing validator, with explicit allowed_evidence_refs. A database capture is a valid scope reference. A schema file about the same table is not automatically evidence for that capture. Validation and provenance requirements are not relaxed.

Each new v3 attempt includes prior validation codes and rejected affected scopes from this revision, plus correction guidance. Feedback is reconstructed only from attempts before the bound operation so later failures cannot change earlier request hashes. A rejected v2 operation can proceed with a new v3 attempt without rewriting its context or its previous calls; attempt limits remain unchanged.

Offline measurement on the local g87 test case: user message 317,069 -> 33,568 characters (89.4% reduction); serialized gateway request 338,972 -> 44,173 UTF-8 bytes (87.0%). All five evidence payloads remain; the offered source catalog shrinks from 209 entries to five proven references. These are deterministic size measurements, not a measured provider token count or quality guarantee.