# Codex Reliability Troubleshooter

> 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.

- Skill: `walterkken/codex-reliability-troubleshooter` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add walterkken/codex-reliability-troubleshooter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/walterkken/codex-reliability-troubleshooter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: walterkken (https://skillmd.com/u/walterkken)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/walterkken/codex-reliability-troubleshooter

---


# 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.

   ```bash
   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

```md
## Codex Reliability Fix

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