From 978588ecffdfb5862f4f5cc9dbd47414bbc696b8 Mon Sep 17 00:00:00 2001 From: jtmorris Date: Thu, 21 May 2026 09:15:27 +0000 Subject: [PATCH] Added guard against useless state caching anti-pattern AI agents keep insisting on. Multiple LLMs keep trying to revert issue #11 unless specifically argued against, and keep sneaking it into code. Other, similar examples of this pathological insistence on storing/caching state that offers no tangible benefit warranting the complexity and edge cases have been tried, but headed off by me earlier. --- AGENTS.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a8d76bb..10c5bda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,8 @@ You **MUST** read each of these documents before contributing to this repository - Repo interaction rules: `docs/agents/repo-instructions.md` - Domain model & context rules: `docs/agents/domain.md` +--- + ## Critical Coding & Version Control Conduct - **NEVER** commit directly to `master` or `testing without explicit human instruction. @@ -12,5 +14,29 @@ You **MUST** read each of these documents before contributing to this repository - **ALWAYS** create new branches when working on non-trivial coding tasks. - **ALWAYS** commit self-contained logical unit of work. +--- + ## Issues, PRs, and Comments Conduct -- **ALWAYS** end your written contributions with `Written by AI agent working for @jtmorris. Model: .`. Replace `` with the LLM model, version, and, if relevant, number of parameters. For example: `Claude Sonnet 4.7`, `Grok 4.3`, `Qwen 3.6 27B`. \ No newline at end of file +- **ALWAYS** end your written contributions with `Written by AI agent working for @jtmorris. Model: .`. Replace `` with the LLM model, version, and, if relevant, number of parameters. For example: `Claude Sonnet 4.7`, `Grok 4.3`, `Qwen 3.6 27B`. + +--- + +## Critical Design Rules +### 1. Only Store or Cache State When It Serves a Purpose + +**Never store or cache state unless doing so meets at least one of:** +1. It is the authoritative source of truth owned by this component. +2. It delivers actionable feedback that meaningfully improves the user experience or a decision. +3. It provides a demonstrable and reasonably argued security or performance improvement (the burden of proof is on the proposer). +4. The information cannot be obtained at the moment it is needed and keeping it produces a clear net benefit. + +Storing state creates a potential disconnect with reality. Managing that disconnect requires extra tests, defensive checks, and cognitive overhead. State should be added only when the benefit is obvious and defensible. + +**Textbook Example (this repository – issue #11)** +Proposal: run `which tailscale` at startup, set a `binaryAvailable` boolean, and guard every `tailscale` invocation behind it. + +**Why this was harmful** +1. Wrong solution to the actual problem. This project is a GUI wrapper around the `tailscale` binary. If the binary doesn’t exist, there is nothing to do except surface an error. Storing a flag and guarding UI actions adds state for no gain. +2. Creates a new class of edge cases that must be tested: the binary existed when the flag was set but later disappears. The code must now defend against both “flag is false” and “flag is wrong.” +3. Unreliable guard for a failure the code must handle anyway. A missing binary produces a clear exit-code failure on the real command. Checking the flag *and* handling the failure duplicates work. +Reference: #11.