From 8abc1a75cfdc72d88bf8cf8f0dbb4d6d9788fbc1 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 4 Oct 2026 05:15:33 +0000 Subject: [PATCH 1/2] Prefer a repository check when guidance only stops a repeated mistake. A review of agent instructions, or of a change that exists only to stop an agent repeating a mistake, should prefer a test, a lint, or removing the need for the instruction before adding another always-on prose rule. Co-authored-by: Dennis Geldmacher --- CHANGELOG.md | 4 ++++ docs/usage.md | 2 ++ skills/context-optimization/SKILL.md | 2 +- .../context-optimization/references/agent-document-design.md | 1 + skills/efficiency/references/design-and-code-simplicity.md | 2 ++ 5 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ffb147c..5d4a9b7 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/usage.md b/docs/usage.md index be400de..c0c0f75 100644 --- a/docs/usage.md +++ b/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 the prose rule when a check cannot express a requirement that must remain available. + To implement a recommendation, ask for it explicitly: ```text diff --git a/skills/context-optimization/SKILL.md b/skills/context-optimization/SKILL.md index 56be419..5cf196b 100644 --- a/skills/context-optimization/SKILL.md +++ b/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. diff --git a/skills/context-optimization/references/agent-document-design.md b/skills/context-optimization/references/agent-document-design.md index 0c9b5e4..d7427b9 100644 --- a/skills/context-optimization/references/agent-document-design.md +++ b/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. Add a new always-on prose rule in `AGENTS.md`, a skill, or a rule only when the agent must still be told the requirement and a check cannot express 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. diff --git a/skills/efficiency/references/design-and-code-simplicity.md b/skills/efficiency/references/design-and-code-simplicity.md index 6dd0e12..b903457 100644 --- a/skills/efficiency/references/design-and-code-simplicity.md +++ b/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. From d69a815199e25a23f792646a0a808aeb79ccf2f6 Mon Sep 17 00:00:00 2001 From: Dennis Geldmacher Date: Sun, 4 Oct 2026 09:38:15 +0200 Subject: [PATCH 2/2] Keep necessary guidance alongside repository checks --- docs/usage.md | 2 +- skills/context-optimization/references/agent-document-design.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index c0c0f75..f8f8fea 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -120,7 +120,7 @@ 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 the prose rule when a check cannot express a requirement that must remain available. +**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: diff --git a/skills/context-optimization/references/agent-document-design.md b/skills/context-optimization/references/agent-document-design.md index d7427b9..6e6df36 100644 --- a/skills/context-optimization/references/agent-document-design.md +++ b/skills/context-optimization/references/agent-document-design.md @@ -24,7 +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. Add a new always-on prose rule in `AGENTS.md`, a skill, or a rule only when the agent must still be told the requirement and a check cannot express 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. +- 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.