| name | aoa-session-recovery |
| description | Diagnose a reviewed recurring session/workflow failure, or carry one bounded owner repair through checkpoint, rollback, and real health verification. Use for reviewed contamination, drift, repeated route/tool failure, or an established diagnosis ready for repair. Do not use on live evidence, for vague self-improvement, or to call a proposed or merely executed change verified. |
aoa-session-recovery
Intent
Recover from recurring session or workflow failure without collapsing symptom,
diagnosis, proposed change, executed change, and verified health into one claim.
Trigger boundary
Use this skill when:
- a closed, explicitly reviewed evidence packet needs diagnosis; or
- a reviewed diagnosis is ready for one bounded repair cycle at its real owner
Do not use this skill when:
- evidence is live, raw, unreviewed, or only a frustration note
- there is no diagnosis for repair, the target owner is unknown, or the route is
a broad playbook-scale rollout
- the requested action would bypass approval, checkpoint, rollback, or owner law
Inputs
- one reviewed evidence packet or reviewed diagnosis, with refs, target and
durable owners, constraints, execution request, approval posture, available
bindings, checkpoint/rollback anchors, and known health surfaces
Outputs
- exactly one typed result from
references/contract.yaml: either a
session-diagnosis or repair-cycle-result, with evidence refs, claim and
execution posture, actual effects, health evidence, uncertainty, and stop line
Procedure
| Mode | Use when | Reference |
|---|
diagnose | Reviewed symptoms exist but causes, drift class, or owner are unresolved. | references/diagnose.md |
repair | A reviewed diagnosis exists and one bounded repair can be prepared, executed, verified, blocked, or handed off honestly. | references/repair.md |
Mode: diagnose
Read and follow references/diagnose.md.
Mode: repair
Read and follow references/repair.md.
- Read
references/contract.yaml and only the selected mode reference to EOF.
- Execute exactly one mode. A diagnosis may hand off to a later repair, but an
invocation must not manufacture a diagnosis and immediately mutate from it.
- Preserve the strongest posture actually proved.
prepared, executing,
executed, and verified are different states.
Contracts
- reviewed session evidence is input, not durable memory or owner truth
- diagnosis is read-only; repair acts only through the target owner's available
tool or repository binding and within the user's authorization
- a repair that changes state requires approval posture, pre-change checkpoint,
executable rollback, bounded retries, post-change health checks, and cleanup
- execution success is not health verification; only observed checks support
verified, and failed checks trigger rollback or an explicit blocked state
- technique records may explain lineage but are not runtime dependencies
Risks and anti-patterns
- self-confirming diagnosis or assigning settled blame from one symptom
- a packet-only response when authorized bounded repair was requested and the
owner binding is available
- changing multiple owners, retrying without a limit, or inventing a validator
as temporary scaffolding
- reporting a preview, diff, command exit, or green unrelated check as health
Verification
- trace diagnosis claims and repair decisions to reviewed evidence or diagnosis
- compare pre/post health on the affected surface and record commands or refs
- confirm actual effects, rollback status, cleanup, remaining uncertainty, and
whether the target owner accepted or still owns the next handoff
Adaptation points
Sessions provide reviewed evidence. Target owners provide mutation, checkpoint,
validation, rollback, approval, and durable-policy contracts.
