Prefer a repository check over another always-on prose rule

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+### Changed
+
+- When a review covers agent instructions, or a change that exists only to stop an agent repeating a mistake, prefer a test or lint the repository can run, or removing the need for the instruction, over a new always-on prose rule.
+
 ## 3.8.0
 
 ### Added

docs/usage.md

@@ -120,6 +120,8 @@ You get specific suggestions about what to keep, combine, or load only when need
 
 **Example:** If three files repeat the same test command, keep one authoritative instruction and clear references to it. If deployment instructions are long and only matter during a release, keep a short pointer that says exactly when to read them. Required security or approval rules must remain available wherever they apply.
 
+**Example:** An always-on rule is proposed only because an agent keeps repeating a mistake. Prefer a test or lint the repository can run, or a change that removes the need for the instruction. Keep concise guidance when the agent still needs the requirement, even if a check also enforces it.
+
 To implement a recommendation, ask for it explicitly:
 
 ```text

skills/context-optimization/SKILL.md

@@ -11,7 +11,7 @@ Before writing a user-facing result, read [the human communication contract](../
 
 Inspect only the context sources relevant to the user's goal. In Cursor, these can include project instructions, rules, commands, skills, and mode guidance. In Codex, these can include global and project `AGENTS.md`, project `.codex/config.toml`, plugins, skills, and repeated command output. In another Agent Plugins client, inspect only context and configuration surfaces documented by that host; do not infer Cursor or Codex paths. Include documentation only when it actually contributes recurring context. Identify duplicated, obsolete, overly broad, or always-loaded material and the constraints that must survive any reduction.
 
-When the scoped context includes skills, `AGENTS.md`, rules, commands, or another document consumed by an agent, read [agent document design](references/agent-document-design.md). Use it to assess pointer quality, persistent versus conditional load, information placement, stale repository-fact caches, and completion criteria. Do not load that reference for ordinary human-facing documentation that does not affect agent context.
+When the scoped context includes skills, `AGENTS.md`, rules, commands, or another document consumed by an agent, read [agent document design](references/agent-document-design.md). Use it to assess pointer quality, persistent versus conditional load, information placement, stale repository-fact caches, completion criteria, and guidance that exists only to stop an agent repeating a mistake. Do not load that reference for ordinary human-facing documentation that does not affect agent context.
 
 Follow the user's requested outcome and the active host mode. An analysis request produces recommendations, native planning uses the host's plan surface, and an explicit implementation request may update only the approved context. If a material edit is not clearly authorized, ask one focused question before changing it.
 

skills/context-optimization/references/agent-document-design.md

@@ -24,6 +24,7 @@ Use this reference only when the scoped context includes instructions or documen
 - Before deleting guidance, trace the entrypoints and references that need it. Confirm that the remaining rule is available on every affected loading path, including references read independently.
 - Remove history, intensifiers, and restatements only when they do not change a useful decision. Retain rationale needed to understand exceptions or boundaries.
 - Prefer stating the required behavior directly. Retain necessary prohibitions as hard guardrails and pair them with the safe target behavior.
+- When guidance or a change exists only to stop an agent repeating a mistake, prefer a check the repository can run, such as a test or lint. Also prefer a change that removes the need for the instruction. Avoid a new always-on prose rule in `AGENTS.md`, a skill, or a rule when a check or structural change makes the instruction unnecessary. Keep concise guidance when the agent still needs the requirement, even if a check also enforces it. An always-loaded rule is read on every task. Recommend that choice; add the check or edit the guidance only when the request already authorizes the change.
 - Make completion conditions observable and proportional. Account for every relevant task case, including omissions that a plausible summary could hide. Replace vague outcomes with evidence an agent can actually inspect, but do not invent ceremony or artifacts solely to prove completion. If later steps pull attention away from unfinished work, clarify the current completion condition first. Recommend an additional document or handoff only when observed behavior shows that the separation earns its context and coordination cost.
 - Preserve security, deployment, environment, domain, package, language, approval, and validation requirements through every reduction.
 

skills/efficiency/references/design-and-code-simplicity.md

@@ -60,6 +60,8 @@ For design simplicity, use the explicitly supplied design or proposal as the sco
 
 Within that scope, check consistent names, cohesive concepts, reuse, derivable state, and redundant parameters. Comments should explain reasons or constraints that code cannot express; use the comment checks above to distinguish redundancy from unclear code. Keep code understandable without conversation history. Remove compatibility only when evidence shows that it was never shipped and every affected caller in scope is updated.
 
+When the change exists only to stop an agent repeating a mistake, read [agent document design](../../context-optimization/references/agent-document-design.md) and apply its preference for that case.
+
 ## Result
 
 For a design or code review, return a concise verdict, material findings with evidence, the root complexity decision when material, practical improvements, required validation, and evidence limitations.