Two failure modes, same codebase, different documents. The first is a principles doc: 'prefer immutable infrastructure, build to fail fast, keep environments symmetrical.' Correct. Useless. Nobody can apply it to a specific decision because it doesn't say how. The second is a tooling doc: 'use Helm 3.x, Terraform 1.4.2+, ArgoCD for GitOps deployments.' Specific enough to follow. Obsolete within 18 months when the stack migrates to Pulumi.
I've maintained both kinds. They both fail. Not because the content is wrong — because the failure mode is built into the structure.
Why both fail
Abstract principles without implementation guidance become decoration. Nobody references them in code reviews. Nobody traces a decision back to 'prefer immutable infrastructure' when debating whether to use a configmap or bake config into the image. The document exists in a wiki. It accrues 12 team members who have never opened it.
Specific tooling docs fight every migration. Every Helm version bump, every cloud provider change, every framework upgrade makes some of them wrong. The people who maintain them spend more time keeping docs current than doing engineering work. And the docs lag reality by two sprints.
The actual failure: both documents are monoliths. They mix things that stay true for years with things that change every quarter. The fast-changing things make the slow-changing things look unreliable. Eventually nobody trusts either.
Separate the layers
The fix is to stop writing monolithic standards and start writing layered doctrine. Principles are durable — true regardless of the current stack. Implementation notes are perishable — correct for today's tooling, explicitly versioned and updated when the stack changes.
When the stack changes, the principle stays. Only the implementation note changes — and it carries an explicit version so teams can track what they're pinned to.
The mechanics
engineering-doctrine ships as a versioned library. Teams depend on it with a pinned version. The principles layer has a slow version cadence — major bumps only when a principle is genuinely wrong. The tooling layer has a faster cadence — it tracks the actual stack.
The result: a runbook pull request that says 'update from doctrine v4.2 to v4.3' changes only the tooling note for the one principle that changed. Not a 40-page document review.
The invariant
Engineering standards go stale when they're written as monoliths. Separate what's true for years from what's true this quarter, ship them at different version cadences, and the doctrine doesn't rot. The principles are stable because they're not carrying the weight of implementation details. The implementation notes are current because they're not pretending to be eternal.