task-observer: docs/ai/writing-docs updates from 2026-06-17

docs/ai/writing-docs.md

@@ -10,6 +10,9 @@ Read this before changing root `AGENTS.md`, `.agents/skills/`, nested `AGENTS.md
 - Keep root `AGENTS.md` under 100 lines unless the user explicitly approves growth.
 - Keep activation text separate from reference content so agents load the source doc instead of guessing from summaries.
 - Write contracts as action + reason + verification. Models follow direct instructions better when the why is visible.
+- Keep compact rationale for judgment-heavy rules. A model must generalize the rule to unlisted cases; without the why, it satisfies only the literal surface form.
+- Keep failure-mode rationale alongside safety-critical rules. Name the required behavior and what goes wrong otherwise. Bare imperatives are easier to rationalize around than imperatives paired with a concrete failure description.
+- When compressing instructions, remove redundancy without reducing enforcement force. Imperative wording and explicit fallback paths guard against known failure modes; preserve them even when shortening for context budget.
 - Lead with the positive action. Use negative wording for known cliff edges, then immediately state the safe path. Reserve `NEVER` or all-caps wording for data-loss, security, or guardrail-bypass risks.
 - Keep one source of truth per concept. Point to it instead of restating it.
 - Move enforceable rules into tooling. Docs are for judgment calls and routing.