geointel/docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md

Codex Run Checklist

Use this checklist at the start and end of every Codex session.

Before starting

• Confirm the current branch/worktree.
• Read CODEX_START.md.
• Read docs/00-start/START_HERE.md.
• Read docs/30-codex-optimization/CODEX_OPTIMIZATION_OVERVIEW.md.
• Read docs/30-codex-optimization/PROMPT_DISCIPLINE.md.
• Read only the active pass prompt.
• Read the relevant skill from skills/.
• Run make readiness if the repository has shell/python available.
• Identify the exact files expected to change.

During implementation

• Keep changes scoped to the active pass.
• Do not introduce new frameworks without ADR.
• Do not change API contracts unless the active pass explicitly requires it.
• Do not create permanent mock-only implementations.
• Prefer small, verifiable service boundaries.
• Keep GIS units and CRS assumptions explicit.
• Record real limitations as limitations, not hidden TODOs.

Before finishing

• Run relevant tests/smoke checks.
• Run make readiness when possible.
• Update docs/CODEX_EXECUTION_LOG.md.
• Update CHANGELOG.md.
• List changed files.
• List what works.
• List what remains incomplete.
• List any deliberate deviations from docs.
• Produce a self-review scorecard.

Stop conditions

Stop and report instead of guessing when:

• a governance invariant would be violated;
• a required external credential is missing;
• a data source license or endpoint is unclear;
• a destructive migration would be needed;
• tests indicate a core regression;
• implementation requires a new major dependency not already approved.