codex-reliability-troubleshooter

name

codex-reliability-troubleshooter

description

Diagnose and harden Codex workflows against common user-reported failure modes: context compaction drift, forgotten AGENTS.md instructions, missing long-term memory, repeated approvals, slow or stuck turns, tool_suggest overhead, and unclear session state. Use when Codex is asked to fix Codex reliability or UX complaints, preflight a long Codex task, recover a resumed or compacted Codex session, tune AGENTS.md/config/permissions, or turn Codex friction into reusable workflows.

Codex Reliability Troubleshooter

Overview

Use this skill to turn Codex friction into durable operating practice. Prefer small, enforceable controls: a clearer prompt, a shorter AGENTS.md, a scoped skill, a permission profile, a handoff file, or a reset/restart checklist.

Read references/public-friction-map.md when public evidence or issue links are needed.

Workflow

1. Classify the failure.

   • context: compaction loses task state, repeats work, or changes progress.
   • instructions: AGENTS.md, global guidance, or rules appear ignored.
   • memory: repeated corrections are not preserved across sessions.
   • permissions: approval prompts are too frequent or confusing.
   • performance: turns are slow, stuck, or the UI hangs on Thinking/resume.
   • scope: the agent expands beyond the approved plan or acceptance gates.

2. Run the optional local preflight.

   python3 scripts/codex_reliability_preflight.py \
     --workspace /path/to/repo \
     --output codex-reliability-preflight.md
   

   Use the script output as evidence. Do not edit config or instruction files unless the user asks for changes.

3. For long tasks, create a non-model handoff trail before implementation.

   • Write the goal, constraints, acceptance gates, active files, commands, known blockers, and current plan into HANDOFF.md, PLANS.md, or the user's existing topic-memory file.
   • Update that trail after major milestones and before context-heavy steps.
   • After compaction or resume, re-read the trail, AGENTS.md, and git status before continuing.

4. For instruction problems, verify discovery instead of assuming.

   • Identify active global and repo instruction files.
   • Check file size and encoding; split large generic rules into references or skills.
   • Put repo conventions in repo AGENTS.md; put repeatable workflows in skills; put one-off constraints in the prompt.

5. For approval fatigue, adjust boundaries rather than bypassing safety.

   • Explain that sandbox and approval policy are separate controls.
   • Prefer workspace-write/:workspace for trusted repos, with narrow writable roots and explicit denies for secrets.
   • Recommend rules for recurring safe command prefixes only after reviewing the exact command and risk.
   • Never tell the user to use full access for convenience alone.

6. For slow or stuck sessions, isolate by layer.

   • Context layer: long chat, huge pasted files, image-heavy history, or repeated compaction. Mitigation: new thread plus handoff.
   • Skill/tool layer: too many skills, tool suggestions, MCP latency, or side-effecting tools. Mitigation: disable or narrow only the costly part.
   • Runtime layer: network/auth, app-server, IDE extension, Remote-SSH, Windows sandbox, or stale processes. Mitigation: collect logs/status and restart the smallest affected surface.

7. Return an actionable fix plan.

   • Diagnosis: one primary failure class and evidence.
   • Smallest durable fix: prompt, AGENTS.md, skill, config, permission profile, handoff, worktree, or restart.
   • Commands/files: exact local commands and paths.
   • Recovery prompt: a short prompt the user can paste into a new Codex thread.
   • Risk: what the fix does not solve or what still needs product support.

Output Template

## Codex Reliability Fix

- Failure class:
- Evidence:
- Immediate recovery:
- Durable fix:
- Files or settings to change:
- Commands to run:
- Stop condition:
- New-thread recovery prompt: