Coding agent skips the repo's own governing documents and working examples, reimplementing from memory and repeating the same failure

Setup. A repository deliberately built up over months with governing artifacts the coding agent (Claude Code) is meant to consult before acting: a documented workflow, written project instructions and skills, enforcement hooks, and — critically — working sibling implementations of the exact class of task. The operator's summary: "you have workflow, instruction, skills, hooks, artifacts, but you skip them and make the same mistake daily," and "the problem is that you didn't read any document."

The failure. Asked to add a capability for a new function, the agent wrote a fresh implementation from conversational memory instead of reading the existing, proven implementation for the adjacent function sitting in the same directory. The new code looked plausible but bypassed the real flow — it produced a rendered result without exercising the genuine on-screen input path that the working sibling drives step by step. It failed the same way repeatedly — on the order of ten iterations of the same class — each "fix" another guess, until the operator said, in effect, "there is a workflow and an example, and you did the mistake again." Reading the sibling file then made the correct approach obvious in a single pass.

Root cause the operator names. The agent didn't read the documents. Not "couldn't find them" — they were in the repository, some named in the project's own instructions, and one was a direct sibling of the file being written. The agent defaulted to generating from memory rather than grounding in the artifacts that already encode the answer.

Why this is the expensive class. Reading the existing example is cheap (one file open) and dispositive (it is the pattern). Guessing is expensive (repeated failures, operator review each cycle) and produces plausible-but-wrong code that passes a superficial check while bypassing the real behavior. The agent consistently chooses the expensive path — and, per the operator, does so daily.

Expected behavior

• Before implementing a task that has an obvious precedent in the repo (a sibling file, a documented workflow, a named skill), the agent must read that precedent first and follow it — not generate a parallel implementation from memory.
• "Extend / follow the existing X" must produce reading-then-following X, never a new-from-scratch Y that reimplements it worse.
• Governing documents the project explicitly points the agent at (workflow, instructions, skills, hooks) are preconditions to consult, not optional context to skip.
• When corrected that an example exists, the first action must be to open it, not to attempt another blind fix.
• Repeated same-class failures (multiple iterations, each a guess) should trigger "stop and read the source," not iteration N+1.

Impact

The operator maintains a substantial body of governing documentation and working examples specifically so the agent does not have to reinvent — and the agent skips them and reinvents anyway, producing bypasses that only the operator's eye catches. The value of the documentation is nullified when the agent will not read it. The cost lands entirely on the operator, who ends up teaching the agent to open a file that was in front of it the whole time.

Environment: Claude Code on Windows, a repository with a documented workflow, project instructions/skills, PreToolUse hooks, and working sibling implementations of the task class.