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

Prompt Discipline for Codex Runs

Codex performs best when each run has one active objective, a clear source of truth, explicit stop conditions, and a small set of expected outputs.

Required prompt shape

Every implementation prompt should contain:

1. Active milestone.
2. Active pass.
3. Required documents to read.
4. Forbidden documents to treat as historical only.
5. Expected files or directories to touch.
6. Expected tests/checks.
7. Definition of Done.
8. Reporting format.

Good prompt pattern

You are working on GeoIntel Kempen.
Active pass: PASS_02_DATABASE_DOMAIN.
Read first: CODEX_START.md, docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md, skills/postgis-migration/SKILL.md, docs/DATABASE_IMPLEMENTATION_PLAN.md.
Do not modify frontend files in this pass.
Implement only the database/domain foundation described in the active pass.
Run make readiness and relevant backend checks.
End with changed files, commands run, tests, risks, next pass.

Bad prompt pattern

Build the whole platform. Improve whatever you see. Make it production ready.

This is forbidden because it causes scope creep, undocumented architecture choices, and conflicting implementations.

Improvement boundary

Codex may improve:

• naming consistency;
• validation details;
• typing;
• docstrings;
• tests;
• small helper functions;
• error messages;
• UI empty/loading/error states;
• non-breaking internal structure.

Codex may not independently change:

• primary stack;
• database choice;
• job queue choice;
• CRS policy;
• API contract shape;
• V1 scope;
• security model;
• storage architecture;
• model governance rules.

Context loading rule

Do not read the entire repository for every pass. Load context in this order:

1. root start files;
2. governance docs;
3. active pass prompt;
4. relevant skill;
5. directly relevant module docs;
6. code files affected by the pass;
7. tests/fixtures for the affected area.

End-of-pass response format

Codex must end each pass with:

## Completed

## Changed files

## Commands run

## Test results

## Known limitations

## Deviations from docs

## Next recommended pass