geointel/docs/M6_FAILURE_RECOVERY_PLAYBOOK.md

M6 Failure Recovery Playbook

Purpose

Codex must recover from failures systematically instead of patching randomly.

Failure classes

Class A — Syntax/import failure

Action:

1. identify failing module;
2. fix import path or missing dependency;
3. add a smoke import test;
4. rerun minimal test;
5. document root cause.

Class B — Database/migration failure

Action:

1. stop destructive changes;
2. inspect model/migration mismatch;
3. create additive migration fix;
4. verify PostGIS extension assumptions;
5. add migration note.

Class C — API contract mismatch

Action:

1. compare endpoint to API contract;
2. fix route/schema/status code;
3. update typed client if required;
4. add contract test.

Class D — Geospatial processing failure

Action:

1. inspect CRS;
2. inspect geometry validity;
3. inspect empty geometry cases;
4. verify projected/unit assumptions;
5. add a small fixture reproducing the issue.

Class E — AI inference failure

Action:

1. check model availability;
2. check CPU fallback;
3. check image tiling shape;
4. check georeference transform;
5. return a structured job failure instead of crashing.

Class F — Frontend state failure

Action:

1. reproduce route state;
2. check API response type;
3. add loading/error/empty state;
4. prevent stale local-only data;
5. add component-level test where possible.

Repair limits

Codex may do targeted fixes in the same pass. If repair requires redesigning a module, Codex must stop and document a recovery plan.

Required recovery note

Every recovered failure must be logged as:

### Failure recovered

- Symptom:
- Root cause:
- Fix:
- Test added:
- Risk remaining: