record-agent-failure

Record Agent Failure

When triggered, make one fast evidence-based classification and call remember_failure once. The tool performs pattern reuse and generalization matching; do not recall lessons or manually compare the store first.

Use these classifications:

• requirement_update, requirement_clarification, preference_update, or ordinary_refinement: the feedback is new work, not a failure.
• real_failure: a prior invariant, inspectable mismatch, material impact or recurrence risk, controllable cause, and durable prevention are evidenced.
• mixed: put only the prior-invariant mismatch in failure_portion; keep new work out of memory.
• insufficient_evidence or uncertain: chronology or required evidence is missing.

Non-failures and uncertain cases use only compact qualification evidence:

{"summary":"compact chronology","classification":"requirement_update"}

For a real or mixed failure, send expectation (invariant, source, evidence), observed (outcome, impact, optional recurrence_risk), cause (layer, failure_mode, component, evidence, recommended_change, verification, optional diagnosis_state, repair_surface, confidence), and lesson (rule, prevention, verification, optional title, applicability, counterexamples).

Find the deepest evidenced controllable cause. layer is one of: skill_instruction, agent_instruction, project_instruction, system_instruction, hook_policy, plugin_manifest, tool_contract, application_logic, adapter_runtime, schema_migration, test_evaluation_gap, harness_limitation, model_behavior, external_dependency, or unknown. failure_mode is one of: missing, ambiguous, conflicting, not_loaded, not_triggered, ignored, incorrectly_implemented, insufficient_validation, uninspectable, or unknown.

Use diagnosis_state=confirmed only for directly supported causes; supported_hypothesis for the best evidence-bounded inference; otherwise unknown. Set repair_surface to the durable instruction, prompt, hook, contract, adapter, implementation, schema, test, or process location that should prevent recurrence. Never invent a root cause merely to record the incident.

If the user identifies an existing lesson_version_id as a requirement change, call report_memory_outcome once with target_type=lesson, outcome=false_positive, source=explicit_user, evidence_kind=user_feedback, and a compact evidence_code instead of recording another failure.

One correction retry is allowed only when the tool returns retryable: true with correction.allowed_values, or the transport rejects a field before execution. If the response includes capture_event_id, copy it to correction_of_capture_event_id; a pre-execution rejection has no capture ID, so omit that field. Correct only the named field. Numeric 0..1 is accepted for confidence. Never retry a non-retryable response, timeout, cancellation, connection loss, or ambiguous error. Never make a third call.

Only when the named tool is absent before invocation, pass the identical JSON once to failure-memory remember. Do not fall back after a tool failure.

Exclude raw prompts, transcripts, secrets, personal data, and unnecessary paths. Briefly report the returned status. A semantic match is only a proposal; history is never silently merged or deleted.