geointel/docs/16-autonomy-governance/FAILURE_RECOVERY_PLAYBOOK.md

Failure Recovery Playbook

Codex must not spiral when a build fails. Use this playbook.

Backend import failure

1. Run the smallest import command available.
2. Fix circular imports first.
3. Verify package __init__.py files.
4. Ensure config does not require unavailable services at import time.
5. Add or update a smoke test.

Database failure

1. Check environment variables.
2. Check whether PostGIS extension is required at migration time.
3. Separate pure unit tests from DB integration tests.
4. Do not remove geometry capability to make tests pass.
5. Document required local Postgres/PostGIS command.

Frontend build failure

1. Run TypeScript check.
2. Fix missing exports/imports.
3. Do not silence errors with any unless documented and temporary.
4. Ensure API types match contract fixtures.
5. Add an empty/error state rather than fake success.

Rasterio/GDAL dependency failure

1. Keep service interface intact.
2. Add graceful unavailable-state handling.
3. Keep GeoJSON/vector paths working.
4. Document local dependency requirement.
5. Do not fake raster metadata as real metadata.

YOLO/SAM unavailable

1. Keep model registry and detection service interface.
2. Implement deterministic fixture inference adapter.
3. Mark adapter as demo/scaffold.
4. Preserve output shape expected by QA/QC.
5. Do not block foundation work.

External data source unavailable

1. Fall back to fixtures.
2. Preserve source adapter contract.
3. Add retry/error state.
4. Do not hardcode one live response.
5. Document the failure in execution log.