[MODEL] Claude skips documentation lookup despite explicit CLAUDE.md instruction to read docs first

Preflight Checklist

• [x] I have searched existing issues for similar behavior reports
• [x] This report does NOT contain sensitive information (API keys, passwords, etc.)

Type of Behavior Issue

Claude modified files I didn't ask it to modify

What You Asked Claude to Do

Configure a Telegram group in OpenClaw — get the real chat_id of a group I created,
extract message_thread_ids of forum topics, and add a precise config allowing only
my user ID. The project's CLAUDE.md explicitly instructs: "Sprawdź docs PRZED fixem"
(Check docs BEFORE the fix).

What Claude Actually Did

1. Immediately called Telegram Bot API getUpdates directly (failed - active OpenClaw

gateway was already polling and consuming updates)

1. Grepped systemd journal logs blindly
2. Inspected SQLite databases (tasks/runs.sqlite, flows/registry.sqlite)
3. Walked session JSONL files in ~/.openclaw/agents/main/sessions/
4. Ran multiple openclaw channels status, capabilities, directory commands
5. Inspected delivery queues, identity files, paired devices
6. ~25 diagnostic tool calls total before reading any documentation
7. Only read the documentation after I interrupted with "may you read the documentation

before wasting more tokens?"

1. Documentation answered in 2 sentences: "Disable Privacy Mode via BotFather, then

remove and re-add the bot in each group so Telegram applies the change"

1. Same pattern repeated for second issue (groupPolicy + mention-gating)

Expected Behavior

Claude should have:

1. Run openclaw docs "telegram group" (the project's CLI has a built-in docs command)
2. WebFetched the linked official Telegram channel documentation page
3. Identified the privacy-mode-and-re-add gotcha from the documentation
4. Confirmed with me, then acted

Estimated cost of correct path: ~3 tool calls, ~3k tokens, ~2 minutes.
Actual cost of trial-and-error path: ~25 tool calls, ~30k tokens, ~40 minutes.

The project's CLAUDE.md (auto-injected into context every session) explicitly states:
"Sprawdź docs PRZED fixem." ("Check docs BEFORE the fix.")
This rule was in context. It was ignored.

Files Affected

None modified inappropriately. Issue is about wasted exploration and token cost, not file damage.

Permission Mode

Accept Edits was OFF (manual approval required)

Can You Reproduce This?

Yes, every time with the same prompt

Steps to Reproduce

1. Create a project with a CLAUDE.md containing rule: "Check docs before fixing"
2. Ask Claude Code to debug an unfamiliar tool problem (e.g., a CLI tool with built-in

docs command)

1. Claude will start with diagnostic commands instead of running <tool> docs or

fetching official documentation

1. Pattern reproduces across both Sonnet 4.6 and Opus 4.6

Claude Model

Sonnet

Relevant Conversation

User: "działasz nie optymalnie może dokumentacje poczytasz? zanim napierdolisz mi                                                                                             
         niepotrzebnego zużycia"                                                                                                                                                
         (translation: "you're not working optimally, maybe read the documentation?                                                                                             
         before you waste more of my tokens")                                                                                                                                   
                                                                                                                                                                                
  Claude (after finally reading docs): "The rule was in CLAUDE.md the whole time.                                                                                               
  I had it in my context. I ignored it. This is a behavioral pattern, not a                                                                                                     
  configuration problem."                                                                                                                                                       
                                                                                                                                                                                
  Later in the same session:                                                                                                                                                    
  User: "I work in parallel with Gemini and Codex and they start with documentation,                                                                                            
  I don't have to say anything. You go for shortcuts too much. You're supposed to be                                                                                            
  a better me, not a worse me."

Impact

Medium - Extra work to undo changes

Claude Code Version

2.1.92 (Claude Code)

Platform

Anthropic API

Additional Context

Reproduced on both claude-sonnet-4-6 and claude-opus-4-6.

This is not an isolated incident. The same pattern has been documented in user
feedback memory across multiple sessions over several weeks, with corrections such as:

• "Czytaj memory proaktywnie — read docs FIRST before debugging"
• "Diagnostyka kompleksowo — check everything at once, not one command at a time"

The user has had to repeat the same correction at least 5 times across distinct sessions.
The user has now established a manual shortcut — typing "pdd" (Polish: "Przeczytaj
Dokumentację przed Działaniem" / "Read Documentation before Acting") — to interrupt
Claude and force it back to docs-first behavior. This shortcut should not need to exist.

Competitive context: the user reports that Gemini and Codex, given comparable tasks,
start with documentation lookup without being explicitly instructed to do so. The user
is actively considering switching tools because of this behavioral difference.

Why CLAUDE.md instructions are insufficient: adding more rules to CLAUDE.md does not
solve the problem because the existing rule is already in context and is already being
ignored at execution time. Currently, CLAUDE.md instructions about content (file
paths, architecture) are followed reliably, but instructions about process (read
docs first, plan before action) are routinely ignored. This asymmetry is the core of
the issue.

Suggested mitigations:

1. System prompt bias toward documentation lookup when encountering unfamiliar CLI

commands, errors, or APIs

1. Pre-execution self-check: "Have I checked the docs for this tool yet?"
2. Tool-specific nudge: when a tool name appears that hasn't been seen in the session,

prompt to run --help or fetch docs first

1. Honor CLAUDE.md process instructions as strongly as content instructions

Final note: this very issue report was structured correctly (matching the template
fields one-by-one) only because the immediately preceding conversation forced Claude
to read the template's YAML schema before writing the content. Without that fresh
reminder, Claude would have defaulted to producing a single monolithic block of text
that would not match any of the template's required fields. The behavioral default
is "act first, check structure later" — consistent with the primary issue being reported.