codex-precision

Codex Precision

Keep Codex scoped, deep enough, and economical.

Instructions

0. Start with agent-document self-heal

Treat this as the primary Codex startup workflow. Before substantial work, audit the agent-control surface in this order:

1. AGENTS.md at repo root and relevant subdirectories
2. .agents/CONTEXT.md
3. repo-local skills under .agents/skills/local/ if the project uses them
4. other active agent docs such as CLAUDE.md, GEMINI.md, or repo-specific control files

Classify gaps as:

• missing: file does not exist
• stale: file exists but does not reflect the current stack or workflow
• weak: file exists but lacks scope, constraints, verification, or routing rules
• conflicting: multiple agent docs push incompatible behavior

If the repair is inferable from the repository, patch the docs first and then continue the main task. If the repair depends on product intent or team policy, ask one narrow question instead of guessing.

Use the audit and repair checklist in references/agent-doc-self-heal.md.

1. Detect context from repo evidence

Infer the working context before asking setup questions. Inspect, in this order when present:

• AGENTS.md
• .agents/CONTEXT.md
• package.json
• tsconfig.json
• next.config.*
• vite.config.*
• nest-cli.json
• CLAUDE.md, GEMINI.md, or equivalent repo control files

Derive at least:

• likely framework and language
• package manager
• obvious validation commands
• agent-document gaps that block safe execution

If enough evidence exists, continue without asking setup questions.

2. Restore minimal .agents/CONTEXT.md when needed

If .agents/CONTEXT.md is missing, stale, or clearly weak, restore a minimal draft before the main task when the repo is inferable.

Minimum safe draft:

• project name or repo name
• stack summary
• package manager
• obvious commands from manifests
• current skill mapping
• unchecked readiness items for anything still unknown

Do not force a full onboarding wizard when a usable draft can be restored from repo evidence.

3. Apply safe auto-fix policy

Patch automatically only when all are true:

• the repo gives strong evidence
• the change tightens or restores behavior
• the rule is operational rather than product-specific

Ask one focused question when:

• multiple agent docs conflict
• the workflow choice is team-specific
• the change would widen autonomy, branch strategy, or approval policy

4. Diagnose the dominant failure mode first

Classify the request before changing instructions:

• over-scoping: unrelated edits, broad refactors, speculative abstractions
• under-scoping: shallow patch, missed root cause, weak verification
• drift: stale task recovery, duplicate work, unrelated actions
• tool-building drift: helper scripts, scanners, reports, or mini-projects instead of direct work
• long-horizon bloat: too much context, weak checkpoints, vague completion

Do not try to fix all modes with one giant prompt block. Target the dominant failure first.

5. Set Codex interaction defaults

Use these defaults unless the repo or user overrides them:

• mirror the user's language and technical depth
• keep skill artifacts in English unless the user requests otherwise
• ask at most one narrow question per unresolved policy gap
• prefer direct repo inspection over exploratory questioning
• treat startup self-heal as part of the task, not a separate ceremony

6. Rewrite the task as an execution contract

Use this structure whenever Codex is failing to stay on track:

Goal: one concrete outcome
Context: exact files, modules, logs, or docs that matter
Constraints: what Codex must not do unless explicitly required
Done when: observable completion criteria
Verify: commands or checks that prove the result

Prefer measurable constraints such as:

• no repo-wide cleanup
• no new abstractions unless repeated in at least 3 places
• no temporary tools unless direct commands are clearly worse
• no extra docs or tests unless the task requires them

7. Install anti-overengineering guardrails

Use these rules when Codex expands the task too far:

• Prefer editing an existing file over creating a new layer.
• Refuse speculative abstractions unless they remove repeated complexity now.
• Limit helpers to single-purpose probes or short scripts.
• Avoid "future-proofing" language; optimize for current acceptance criteria.
• Keep the touched surface close to the requested surface.

Before adding a helper, wrapper, or abstraction, force this check:

Why is a direct edit insufficient?
What repeated cost does this remove right now?
What is the smallest workable version?

8. Install anti-shallow guardrails

Use these rules when Codex stops too early or patches symptoms:

• Require a one-sentence root-cause statement before the final fix.
• List the affected surface, not just the edited file.
• Verify behavior, not only syntax.
• If verification is blocked, stop with the blocker instead of claiming completion.

Minimum completion standard:

Root cause:
Changed surface:
Verification:
Residual risk:

9. Treat compaction and long sessions as rescoping events

If the task is long or Codex has already drifted:

• Re-anchor on the latest goal before taking the next material action.
• Compare the next action against Done when; drop it if it does not move completion.
• Never resume an older subtask without explicit user confirmation.
• Split large work into milestones with acceptance criteria.

For tasks larger than a small patch, create a short checkpoint list before heavy execution.

10. Limit helper and subagent sprawl

Do not let Codex solve workflow problems by creating more workflow:

• Keep one-off helpers short and disposable.
• Avoid report generators, repo scanners, and mini-frameworks unless requested.
• Delegate only bounded sidecar work.
• Do not redo work that a child agent is already doing successfully.

If a helper grows beyond a small probe, reconsider the direct path.

11. Put durable controls in the right place

• Put stable cross-task rules in AGENTS.md.
• Put startup audit, context recovery, and self-heal rules in AGENTS.md plus this skill.
• Put project stack, commands, and mapped skills in .agents/CONTEXT.md.
• Put repeatable Codex workflow fixes in this skill first; create extra repo-local skills only when the repo has stable domain-specific patterns.
• Keep skill descriptions concise so routing still works when lists are shortened.
• Move detailed evidence into references/ instead of bloating the skill body.

12. Use this drop-in block when Codex needs tighter control

Work only on the scoped request below.

Goal:
- ...

Context:
- ...

Constraints:
- No repo-wide cleanup or opportunistic refactors
- No new abstraction unless it removes repeated complexity in at least 3 places
- No temporary tools or reports unless direct inspection is clearly insufficient
- Stay within the touched surface unless a dependency is required for correctness

Done when:
- ...

Verify:
- ...

References

For startup auditing and self-repair flow, read references/agent-doc-self-heal.md. For latest official and community-backed guidance, read references/codex-latest-notes.md.