Terms in this guide: Acceptance criteria · Verification
Diagnose discovery, context, tool, permission, environment, and validation problems without adding random instructions.
Codex cannot see my project instructions
Confirm the working directory and the instruction files between that directory and the repository root. Check whether an override file takes precedence and whether the session began before the latest change. Ask Codex to summarize the instructions it actually loaded.
Do not solve discovery failures by copying every instruction into the prompt. Fix the scope or file placement so future tasks receive the same durable context.
A skill does not appear or trigger
Check the folder name, SKILL.md frontmatter, discovery location, and description. Start a new session or restart the client after changes when required. Invoke the skill explicitly to separate discovery from trigger matching.
If explicit use succeeds but automatic selection does not, revise the description around the actual task and boundaries. Avoid adding a long keyword list that attracts unrelated requests.
A plugin or MCP tool is unavailable
Confirm the current client supports the plugin or connection, the plugin is enabled for the new conversation, and the server has completed any required authentication. For local MCP, inspect the configured transport, command or URL, environment variables, and restart requirement.
Test a read-only tool call with a small input. Treat installation, authentication, authorization, and tool execution as separate checkpoints.
A worktree cannot start the application
Check whether dependencies, generated files, or ignored configuration are missing from the isolated checkout. Run the documented setup action and compare it with the main checkout. Do not copy a broad secrets directory into every worktree to make one test pass.
The result looks plausible but is wrong
Return to the acceptance evidence. Reproduce the current behavior with a concrete input, inspect the changed files, and run the smallest meaningful test. A fluent explanation is not evidence that the repository, page, or external system behaves that way.
Record whether the issue came from missing context, a wrong assumption, incomplete validation, or an implementation defect. Correct the responsible layer rather than accumulating defensive prose everywhere.
A task is stuck waiting for access
Identify the exact file, network destination, command, account, or action that requires permission. Complete any independent analysis first. Request only the narrow access needed and explain which result it unlocks.
If the task cannot proceed, leave a reproducible status: completed work, blocking condition, evidence collected, and the next safe action.
Reduce the problem before changing configuration
Begin with one failing request and a known starting state. Record the client, project path, selected environment, relevant extension or plugin, and the first useful error. Then remove optional integrations or instructions one at a time. Changing several settings at once can make the symptom disappear without revealing the cause.
Compare discovery, access, execution, and verification as separate stages. A skill that does not appear is a discovery problem. A tool that appears but cannot authenticate is an access problem. A command that runs and produces the wrong file is an execution or instruction problem. A plausible answer without evidence is a verification problem.
Write a useful support record
A support record should include exact reproduction steps, expected and actual behavior, the first error, environment details, and attempts that changed the result. Redact secrets and personal data. Prefer a short log fragment around the causal event to a complete noisy session.
When a workaround succeeds, state whether it restores the intended behavior or only bypasses the failing feature. Keep rollback instructions for configuration changes. If the issue cannot be reproduced, list the missing state instead of guessing at a fix.
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.