Garden
A digital garden of interconnected notes — ideas at various stages of development.
🌳 Evergreen (69)
AI Collapses the Economic Moat of Clean-Room Reimplementation
The copyleft moat was never purely legal. It was economic: compliance was cheaper than reimplementation. AI collapsed that cost.
Align Alerts to SEV Criteria
Alerts should fire at or near the threshold where an SLO breach would occur, not well before.
Backward Compatibility for Leaky Abstractions
When a framework leaks implementation details (like serializing arguments at schedule time but loading code from HEAD at execution time), changing a function signature breaks the assumption that old code calls old signatures.
Check If Concern Is Systemic
Before resolving a concern, check whether it is isolated or systemic.
Command Control Misnomer
"Command and control" is a misnomer for directive governance.
Contributor Poker: Review as Investment
In open source maintenance, PR review is not quality assurance — it is investment in a contributor's long-term development.
Convert Ambient Knowledge into Local Context
The core design principle for the suggestible actor: convert ambient knowledge into local context.
Copyright Is the Sole Enforcement Mechanism for Open Source
Every open source license is a conditional grant of copyright, and copyright is the only enforcement mechanism that sustains open source.
Coupled Tests
Coupled tests (tests whose outcomes depend on other tests through shared mutable state, execution ordering, or shared infrastructure) are one of the most corrosive anti-patterns in a test suite.
Coverage Metrics Are Misleading
Coverage tells you which code was executed during tests, not which behavior was verified.
Defense in Depth Needs Visibility
Defense-in-depth only works if every fallback layer is visible and monitored.
Detroit vs. London Schools of Unit Testing
The Detroit and London schools define "unit test" differently, driving fundamentally different strategies.
Directive Governance
Directive governance is the pattern where information flows up (compressed and lossy), decisions are made centrally based on that compressed information, directives flow down for execution, and accountability is for compliance with directives rather than for outcomes.
Directive Governance Is Not Keynesian
Directive governance is not Keynesian central planning.
Essential Complexity Makes Software Ungovernable
Essential complexity makes software organizations ungovernable from the top.
Every Mutation Needs an Undo
Every script that mutates system state should build an undo alongside the forward operation.
Explaining Away Concerns Is Victim Blaming
Never become an apologist for the organization when someone raises a concern.
Fakes Over Stubs
Prefer fakes over stubs when the dependency has stateful behavior.
Friction Requires Intent
Ergonomic friction as a design tool only works when the actor has intent and judgment.
Git Conflicts with Trunk-Based SaaS Workflows
Git's distributed, branch-heavy design conflicts with trunk-based continuous deployment workflows.
Goal vs. Intent
Goal and intent are not the same thing.
In Software Execution Is Decision Making
The decision/execution boundary that directive governance depends on does not exist in software.
Law of Demeter and Testing
Demeter violations in production code become mock chains and bloated test fixtures in test code.
Listen Before Solving Concerns
When a team member raises a concern, the manager's first job is to understand, not to solve.
Minimize Public Surface for Testability
If a class is only used internally by another class, don't test it directly.
Mission, Not Price, Coordinates Subsidiarity
Subsidiarity coordinates through shared mission, not price signals.
Mocks in Testing
Mocks verify outbound interactions from the SUT to its dependencies.
Mocks vs. Stubs: When to Use Which
Stubs and mocks serve fundamentally different purposes and should not be used interchangeably.
Never Sacrifice Test Accuracy
Never sacrifice test accuracy.
Privacy in Processing vs. Privacy in Identity
Privacy frameworks split on where rights attach: to what is done with data (processing) or to whether data can be traced back to a person (identity).
Reduce Cyclomatic Complexity
Cyclomatic complexity measures independent execution paths through a function.
Reuse Code, Not Objects
DRY applies to code, not to object instances.
Shadow-Verify-Migrate Pattern
Migrate between service implementations in three composed steps: shadow, verify, switch.
Simplicity Over DRY in Tests
DRY is near-universal in production code, but applying it dogmatically to test code causes more problems than it solves.
Structurelessness Hides Hierarchy
Eliminating formal hierarchy does not eliminate hierarchy.
Stubs in Testing
Stubs replace inbound interactions from dependencies to the SUT by providing canned responses so the test controls what the SUT sees.
Subsidiarity
Decisions should be made at the lowest level competent to make them.
Subsidiarity Is a Third Position
Subsidiarity is a third position, not a pole on the Keynes-to-Hayek spectrum.
Subsidiarity Is Not Flat Organization
Subsidiarity preserves hierarchy but changes what it is for.
Subsidiarity Preserves Hierarchy
Subsidiarity preserves hierarchy; Hayek's market does not.
Survival vs. Excellence as Engineering Modes
Software development has two modes (survival and excellence), and the choice should be deliberate, not a default.
TDD for Bug Fixes
Bug fixes should follow a TDD workflow split across two PRs.
Test Behavior, Not Implementation
Test what a system does (brains), not how it does it (nerves).
Testability Forces Dependency Injection
Testability forces dependency injection: code that constructs its own dependencies internally is untestable without expensive integration infrastructure.
Testability Forces Modularity
Hard-to-test code is a design smell: if a class is hard to test, it is doing too much.
Tests as a Refactoring Safety Net
Unit tests transform refactoring from a high-wire act into a routine operation.
Tests as Executable Documentation
Unit tests are the best documentation for code.
Tests as First Customer
Writing unit tests makes you your own first customer.
Tests Exist for Maintainability
The fundamental purpose of unit tests is not verification.
Tests Prune the Debugging Search Space
Every code path covered by a passing test is a path you can rule out during debugging.
The AI Agent Category Error
Placing the AI coding agent on the intent spectrum is a category error.
The AI-Assisted vs. AI-Generated Boundary Is Legally Undefined
The Copyright Office says AI assistance does not bar copyrightability but has not defined where AI-assisted ends and AI-generated begins.
The Detroit School of Unit Testing
The Detroit (classical) school defines a unit as a unit of behavior: one or more classes collaborating to produce an observable result.
The Directive Gap
The directive gap is the distance between the human's goal (with all their ambient knowledge) and the context actually available to the agent during execution.
The Empty Grant: AI-Generated Code Creates Unenforceable Licenses
AI-generated code is not copyrightable, which means it cannot carry license conditions.
The Failure Argument Is Conditional
The argument that directive governance fails in software is conditional, not universal like Hayek's.
The Hollow Commons Schism Pattern
When an AI-powered downstream fork produces improvements that the upstream community refuses to accept, the commons splits into an AI-accelerated branch and a human-maintained branch.
The Intent Spectrum
All software design assumes an actor with intent.
The London School of Unit Testing
The London (mockist) school defines a unit as a single class, sometimes a single method.
The Open Source Ouroboros
Open source code is the primary training data for the AI models that undermine open source, creating a feedback loop with no exit within the current framework.
The Ratchet Has No Market Analog
The crisis-centralization ratchet has no analog in markets.
The Suggestible Actor: Four Properties
The suggestible actor is defined by four properties that together predict its failure modes.
Unit Test Attribute Trilemma
Unit test suites have three attributes in tension: accuracy (if a test fails, is there a real bug?
Upward Comms Asymmetric Commitment
Asymmetric commitment kills upward communication: leadership demands it without reciprocating downward.
Upward Comms Format Obsession
Format obsession in upward communication displaces substance with compliance.
Upward Comms No Engineer Buy In
Upward communication processes designed for management without consulting contributors are dead on arrival.
Upward Comms Unresponsiveness
When upward communication vanishes without acknowledgment, contributors learn the process is performative.
Upward Communication Anti Patterns
Upward communication fails because organizations ignore the power differential that makes it inherently fragile.
VCS Should Match Your Development Model
Your version control system should fit your development model, not the other way around.
🌿 Budding (15)
Confabulation Is Plausible
AI agent confabulation is not random — it is plausible-looking wrongness constructed from pattern and proximity rather than knowledge.
Crisis Centralization Ratchet
Tech companies centralize decision-making during crisis and almost never decentralize afterward.
Data Pipeline Is Achilles Heel
The data pipeline is directive governance's Achilles heel, not the decision-maker's rationality.
Delegation Mimicry Without Cultural Substrate
Most tech CEOs copy the structural form of delegation without the deliberate cultural investment that makes it work.
Directive Governance Cargo Cult
Directive governance in tech is a mechanistic-organic hybrid cargo cult.
Directive Governance Degrades Not Destroys
Violating directive governance's preconditions predicts degraded performance cushioned by market position, not immediate collapse.
Directive Governance Preconditions
Directive governance fails when its three structural preconditions do not hold: compressibility, proxy validity, and separability.
Isomorphic Mimicry In Tech Governance
Tech companies adopt directive governance through isomorphic mimicry: copying a governance model from industries where it works without verifying that the preconditions hold.
Metrics Measure Maintenance Not Creation
Metrics measure maintenance, not creation.
Partial Measurement Worse Than None
Partial measurement is worse than no measurement.
Serial Satisficing Without Learning
Organizations serial-satisfice without learning: each correction is made under the same information constraints as the decision it corrects.
Susceptibility Peaks at Failure
An AI agent's susceptibility to local context peaks at the point of failure.
Three Assumptions Framework
Directive governance rests on three implicit assumptions about the information pipeline.
Tooling Advances Prove Brooks Right
Every advance in software tooling proves Brooks right.
Unfalsifiable Organizational Corrections
Organizational corrections are unfalsifiable: executives assert rationality without evidence, and the counterfactual is untestable.