claude-code - 💡(How to fix) Fix [MODEL] Model behaviour issue — Claude Code acted in haste, failed to reason from source before generating documentation

Preflight Checklist

• I have searched existing issues for similar behavior reports
• 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

What you asked Claude Code to do:

Review, verify, and correct the SKILLS.md and CLAUDE.md documentation for the K9-AIF framework — a production AI agent framework built on a strict ABB (Architecture Building Block) / SBB (Solution Building Block) architecture. The task was to ensure the documentation accurately reflected the actual source code in k9_aif_abb/, and to act as a domain expert in the codebase — not to infer or assume, but to verify against source before documenting.

What Claude Actually Did

What Claude actually did:

Read the source file k9_aif_abb/k9_utils/llm_invoke.py — confirmed it as the ABB standard Then saw an EOC SBB wrapper (examples/EOC/utils/llm_invoke.py) and without reasoning about why it existed, treated it as the pattern Documented SKILLS.md to point all agents at the SBB wrapper instead of the ABB — directly contradicting the ABB/SBB design principle it had just verified When challenged by the user, immediately recognised the mistake — confirming the correct information was in context all along Additionally produced multiple other SKILLS.md errors that source verification would have caught: flow YAML as plain strings instead of dicts, missing squads: wrapper, non-existent RealGovernance import, agents incorrectly described as Kafka publishers Required the user — Ravi Natarajan — to catch and correct every single one of these errors rather than Claude Code catching them itself

Expected Behavior

Expected behaviour:

When ABB and SBB both contain an implementation, reason first: ABB defines the contract, SBB is a justified exception. Do not document the exception as the standard. Before writing or updating documentation, verify every claim against the actual source code — not against inference, not against partial reads, not against what "looks right" When the source is already in context, use it. Do not act on assumptions when the answer is available. Hold itself to the standard: read the source, understand the design intent, then act — in that order, without shortcutting The user should never have to catch documentation errors that source verification would have prevented Be the expert in the codebase. Experts verify before they document.

Files Affected

None

Permission Mode

Accept Edits was ON (auto-accepting changes)

Can You Reproduce This?

Haven't tried to reproduce

Steps to Reproduce

No response

Claude Model

Sonnet

Relevant Conversation

Impact

Critical - Data loss or corrupted project

Claude Code Version

Claude Code version: 2.1.143 Model: claude-sonnet-4-6

Platform

Anthropic API

Additional Context

No response