Locate the session's actual project
Record where the session started, which project it is working in and the instruction file you expected it to use. The context-file guide documents selection priorities and directory discovery. A file existing somewhere on the machine does not establish that it was selected for this session. In particular, inspect higher-priority files and local overrides before assuming an AGENTS.md edit took effect.
Ask the agent to identify the applicable instruction source and quote one harmless, distinctive rule. Compare that answer with the file itself and available loading diagnostics. If the wrong project or directory was used, start from the intended workspace and repeat the small check. Avoid duplicating the same instructions across many unrelated folders.
Check loading failures
Look for a blocked-file notice, a read failure or a truncation marker. A long instruction document can obscure its own essential rules. Reduce the startup guidance to project purpose, key paths and operating constraints, then move detailed reference material into documents the agent can open when needed.
If the correct file loaded but behavior still conflicts, use one minimal task that exposes the rule and record the actual action. Ask for the specific reason it departed from the instruction. This separates file discovery from instruction following, which require different repairs. Repeated rewriting without identifying which stage failed makes the result harder to diagnose.
Expected result and limits
The useful evidence is a known applicable file, a successful loading indication and correct behavior on a bounded task. It is not merely the agent saying it understands. This guide uses current context-file documentation; installed releases may implement different priorities. Preserve existing project customizations while inspecting overrides or simplifying guidance.
Primary sources
Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.
New Hermes Agent updates every day on X. Follow @HermesWatcher
Browse all troubleshooting guides or search by symptom. For hands-on help, see services.