Standards Decisions Need Decision Records
Jun 23, 2026
Engineering standards work can look like documentation, but it often carries policy weight. If a team records standards without separating evidence, recommendations, decisions, and implementation status, the document can accidentally turn drift into authority.
The problem
Teams often discover standards drift in ordinary places: README commands, package scripts, runtime versions, workflow ownership, test expectations, build gates, and deployment assumptions.
The tempting response is to clean everything up at once. Update the docs, normalize the scripts, change CI, and call the standard fixed.
That is risky when the repo does not already answer the policy questions. A codebase can show what has happened; it cannot always decide what should become the standard. Package managers, runtime versions, workflow ownership, integration-test gates, and build requirements may require an explicit human decision.
Documentation can make policy by accident
A standards reference is not an ordinary doc page. Future work will treat it as authority.
That means the document should not blur five different things:
| Category | What it answers | | --- | --- | | Repo fact | What is true in the repository today? | | Recommendation | What does the worker or reviewer propose? | | Human decision | What has an accountable person accepted, rejected, or deferred? | | Deferred question | What remains unresolved and should not be implemented yet? | | Implementation status | Has the accepted decision actually changed code, scripts, CI, or docs? |
Without that separation, a recommendation can be mistaken for a decision, a decision can be mistaken for an implemented change, and an observed inconsistency can become the default standard simply because it was written down.
Decide before implementing
For CI and script cleanup, a decision record should come before the implementation item.
That may feel slower, but it avoids a common failure mode: using a cleanup task to quietly encode policy. The safer sequence is:
- Audit the current repo facts.
- Identify where the repo cannot safely decide the standard.
- Present recommendations separately from facts.
- Record human accept, reject, or defer decisions.
- State explicitly which decisions are only recorded and not yet implemented.
- Create a later implementation task with fresh verification of the facts it relies on.
This keeps a narrow documentation change from becoming an unreviewed CI migration.
Verification should check the boundaries
Verification for a standards decision record should not only ask whether the document exists.
It should confirm that required decision rows are complete, no unresolved decision markers remain unless intentionally deferred, accepted decisions have not been silently implemented, and the diff did not touch scripts, lockfiles, workflows, app code, or configuration outside the item scope.
It should also check the document for stale wording. If a section still says a decision is pending after the decision has been recorded, future readers may treat the reference as less reliable than it is.
The broader principle
Standards references are governance artifacts.
They are useful because they make future work easier to execute, but that usefulness depends on clear authority. The best version does not just say what the standard is. It shows what evidence supports it, who decided it, what remains deferred, and whether the codebase has actually been changed to match.
When the question is policy, do not hide the decision inside the cleanup.
Write the decision record first.
