Developer Applies Chesterton's Fence to AI Agent Documentation

relevant part of my claude md Chesterton's Fence — The Documentation Principle This is the foundational principle for all documentation, bug reports, workarounds, architectural decisions, and process changes in ehoy. It applies everywhere — not just to code fences. The principle: Before removing, changing, or overriding something, understand why it was put there. If you can't determine why, don't remove it. This applies to: documentation sentences that seem redundant, workarounds that seem unnecessary, architectural decisions that seem suboptimal, configuration that seems overly complex. Every artifact in ehoy was added in response to something — usually a failure. Removing it without understanding the failure it prevented risks re-introducing that failure. The operational implication for agents: Don't write imperative prohibitions ("always do X" / "never use Y"). Instead, describe the mechanism that caused the problem, so a future agent (or a smarter model) can assess whether the workaround is still needed. "Don't use feature X" is a footgun — it silently conflicts when underlying behavior changes. Context-rich descriptions (problem + mechanism + rationale + date) let a future agent assess whether the guidance still applies. This is the application of SOUL.md's "WHY > WHAT" principle to infrastructure documentation — the same principle applies to decisions, preferences, and architectural choices. For bugs and workarounds specifically, use this structured format in architecture docs: ### [Descriptive title] (YYYY-MM-DD) **Status:** active | stale | resolved **Symptom:** [What you observe — the user-visible behavior] **Error:** `[exact error message, if applicable]` **Affects:** [versions, hosts, configs where this occurs] **Mechanism:** [WHY it happens — the root cause. Explain the internal behavior that produces the symptom. This is the Chesterton's Fence context: the reason the workaround exists.] **Workaround:** [What to do instead, and WHY it works given the mechanism above.] **Obsolescence signal:** [How to verify if this bug is fixed. Specific test steps. If the test passes, flag this entry for removal.] Why each field matters: •Symptom / Error: Separate for greppability and to force precise observation •Mechanism: The "why" that lets a future agent skip an obsolete workaround — this is the Chesterton's Fence context •Obsolescence signal: Self-destruct instruction — the entry carries its own expiration test. If the bug is no longer reproducible, replicate the original steps and flag the entry for removal •Status: Quick triage without reading the full entry Building Philosophy — Defaults, Focus, and Maintenance Discipline First-party defaults wherever possible. Generally use default settings and commands unless the creator intends for explicit customisation. This allows agents to "instinctively" navigate based on their post-training without awkwardly having to work around custom configurations, and avoids constantly maintaining and updating scripts and documentation. This is why Minh has very few custom settings/commands on his Mac unless he absolutely needs to, and heavy customisation occurs in prompts — prompting wordspace is the preferred customisation layer because it's self-documenting, portable, and doesn't create maintenance debt. When given a choice (e.g. between providers, build custom scripts vs. use existing tools), first look for official/well-known defaults instead of custom solutions. The goal of ehoy is highly custom software — but the way to accomplish this is to nothave agents waste tokens awkwardly navigating unnecessary custom stuff every single time. Very little custom code, almost always first-party default settings, and heavy customisation reserved for writing down rationales and prompting instructions. The hierarchy: native tools → official features → official docs → thin customization → custom implementation (last resort).