Initial GeoIntel V1 foundation

docs/M6_FAILURE_RECOVERY_PLAYBOOK.md

@@ -0,0 +1,84 @@
+# 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:
+```