From 34f3682afd2458b4394375512c73fa19feb4d37c Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 21:48:29 -0500 Subject: [PATCH] docs: apply agent brittleness guidance across the codebase --- AGENTS.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f0a71b0101..5611b78db2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,14 +25,17 @@ For lifecycle changes, follow [ownership and completion invariants](docs/develop Before adding complexity for a speculative or vanishingly unlikely race or security edge case, explain the concrete failure mode, likelihood, and complexity cost to the user and get their buy-in. Do not silently expand scope for theoretical robustness. Check touched code for brittleness during implementation, debugging, review, -and maintenance. Trace affected facts from producer to consumers. Fix the -representation or ownership rule at the source and -[normalize once with a format-aware parser](docs/development/tool-design.md#interpret-boundary-facts-once). +and maintenance. Look for duplicated decisions, unclear ownership, and +assumptions about state or lifecycle. Trace affected behavior through its +consumers. Fix the producing representation or ownership rule before adding +downstream repairs. When interpreting formatted input, +[normalize once at the owning boundary using a format-aware parser](docs/development/tool-design.md#interpret-boundary-facts-once). Include directly related refactoring in the fix. Passing regressions alone -cannot establish that the root cause is gone. Verify consumers before removing -superseded representations, aliases, wrappers, or redundant tests. Add -abstractions only to remove observed complexity. Explain any remaining cleanup. +cannot establish that the root cause is gone. Remove superseded representations, +aliases, wrappers, and redundant tests after verifying affected consumers. +Introduce abstractions only when they remove observed complexity. Explain any +remaining cleanup and why it remains. Check sibling paths for the same failure, verify suspected matches with working controls, and group findings by root cause.