From 13afe0144135ff743d2ebe2f83dccbc550f4d33a Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Thu, 29 Oct 2026 21:37:41 +0800 Subject: [PATCH] docs(agents): prefer upstream fixes over local workarounds Clarify that minimality means the smallest best-practice change, not a local patch around an upstream defect. Assisted-by: DeepSeek Harness (deepseek-flash) --- agents/global-rules.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/agents/global-rules.md b/agents/global-rules.md index c6f9ef83..d1c44add 100644 --- a/agents/global-rules.md +++ b/agents/global-rules.md @@ -118,6 +118,10 @@ For an impactful change, follow these steps in order, scaled to its risk: provides over a new one, and reuse existing config and abstractions instead of duplicating them. Agents MUST NOT delete config the task did not ask about; when config merely appears unused, report it instead. Ask before a breaking change. +- Minimality is not a reason to encode a local workaround for an upstream defect. Fix the owning + upstream project first and consume the fixed revision; if a local stopgap is genuinely unavoidable, + stop and ask the user before adding it. "Minimal" means the smallest change that follows existing + best practice, not the smallest diff at any cost. - Documentation should describe current behavior for readers without the conversation history; give each fact one home per audience and link instead of repeating. Comments explain contracts or non-obvious constraints, not obvious code, and preserve safety, license, and workaround