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 and use change_request_v2. 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.