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:

```md
### Failure recovered

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