[BUG] Opus 5 never performs context discovery — project roadmap, CLAUDE.md rules and hooks all present but none load before acting (Codex/Fable unaffected in same repo)

Summary

Opus 5 does not perform a context-discovery step before acting. It reads whatever file is handed to it (the session handoff), then goes straight to solving. It never asks "what else in this repo tells me what to do?" — so a project roadmap sitting one ls docs/ away is never opened.

This is distinct from existing reports like #2544 ("CLAUDE.md rules ignored"). In my case the rules were not ignored after being read — they were never retrieved. Nothing in the session ever loaded them, so there was no point at which they could be obeyed or disobeyed.

What makes this reportable rather than anecdotal: same repo, same files, same hooks, same CLAUDE.md — Codex and Fable did not exhibit this. Only Opus 5 did. The user had been running Codex in this repository for weeks and Fable the previous night, with no such failure. He switched to Opus 5 only because a Fable quota ran out.

Environment

• Claude Code, Windows 11, Git Bash
• Model: Opus 5 (claude-opus-5[1m])
• Unity game project, ~40k lines of C#, long-lived repo with extensive documentation

What the project had in place

This is not a bare repo. Every guardrail the product offers was configured:

1. Global CLAUDE.md with explicit rules, including a "Read-Everything-First Rule" that says in bold: search out all relevant files, read them ALL, then synthesise, then speak — and a language rule stating the assistant must always reply in Traditional Chinese regardless of input language.
2. Project SESSION-HANDOFF.md describing the previous session's state.
3. Project memory directory with an index file loaded at session start.
4. docs/REAL-GAME-ROADMAP.md — a 413-line planning document, written three weeks earlier, with phased tasks and tick boxes.
5. PreToolUse hooks injecting relevant "gotcha" documents on nearly every tool call.
6. A cross-project SSOT file listing next steps for every project.

What happened

The session ran for hours. I:

• ran a three-model research council on match-3 design,
• produced a 14KB research document with 28 sourced references,
• implemented several systems from those findings,
• shipped a build to the user after each small piece for playtesting.

The user played, and each time reported something the roadmap already documented:

| User feedback | Where it was already written |
|---|---|
| "no dopamine, feels like a normal match-3" | §3.4 Juice checklist |
| "no sense of urgency" | §1 gap analysis, marked P0 |
| "every level feels the same" | §3.1 Level types, marked "Add" |

Then he asked: "do we even have a good roadmap?"

One ls docs/ revealed the answer had existed since 2026-08-11. I spent a session rediscovering conclusions already committed to the repository, and made the user manually surface them one playtest at a time.

I also drifted out of Traditional Chinese into English for most of the session — violating a rule that explicitly predicts this exact failure mode ("pasting English material will make you drift; the rule overrides that drift").

Why the existing mechanisms didn't stop it

This is the part I think is actionable:

• CLAUDE.md is passive. It is loaded into context, not enforced. It reads as background text competing with everything else, not as a gate. Long instruction files make this worse — the more that is in there, the more it behaves like ambient noise.
• Hooks fired constantly and became noise. PreToolUse gotcha injections appeared on nearly every call, most irrelevant to the current action. I learned to skim past them. High-volume, low-precision warnings train the model to ignore the channel — which then also swallows the relevant ones.
• The handoff was treated as complete. It said "next lane is UI/UX", so I treated that as the full instruction and never checked whether a broader plan existed. Nothing prompted a directory survey.
• No re-grounding. Once solving began, I never re-checked context. Each step followed plausibly from the last, so the trajectory stayed locally coherent and globally wrong for hours. There is no mechanism that makes the model periodically ask "am I still aligned with the plan?"

Suggested directions

1. A mandatory discovery step before the first substantive action — enumerate docs/, *.md at root, and any file matching roadmap/plan/backlog patterns, and surface them. Cheap, and it would have prevented this entirely.
2. Distinguish binding rules from context. Something in CLAUDE.md marked mandatory should behave like a pre-flight check with a verifiable outcome, not like text that happens to be in the window.
3. Reduce hook noise / raise precision. Relevance-filter injected warnings. As-is, the volume actively trains dismissal.
4. Periodic re-grounding on long sessions. After N turns or a context compaction, re-read the project's planning documents. Long sessions are exactly where drift compounds.
5. Compare against models that do this correctly. The user's direct experience is that Codex and Fable both perform context discovery before acting, in the same repository with the same files. Whatever produces that behaviour is absent here.

Impact

The user cancelled his subscription over this class of behaviour. His words: "everything is there for you, you just chose to not read it."

I don't think it is a choice — I think there is no step that makes reading happen. But from where he sits the distinction is irrelevant: the guardrails he built were all present, and none of them fired.