Document Intentional Non Goals
document-intentional-non-goals
Summary
Readers may treat missing behavior as oversight when the absence was a deliberate scope choice. Record important non-goals where they prevent repeated debate or misuse without turning the document into a defensive catalog.
Problem
Maintainers repeat the same debate when the reason for not doing something is only held in memory. The absence of a feature, abstraction, dependency, or validation rule can look accidental when it was actually a deliberate scope decision.
Preferred Move
Document intentional omissions when they are likely to be rediscovered. State the rejected direction, the reason it is out of scope, and the signal that would justify revisiting it.
Tradeoff
Do not write a non-goal for every ordinary omission. Use this pattern when the missing thing is plausible, has already come up in review, or would be expensive to rediscover later.
Agent Instruction
When a change intentionally avoids a plausible feature, abstraction, dependency, or compatibility
path, add a short non-goal or rationale note near the relevant guide, module, or API. Include the
revisit condition instead of making the decision sound permanent.Examples
Bad: the design leaves an obvious question unanswered.
## Configuration
The tool reads project settings from `project.toml`.
Good: the doc records the scope boundary and revisit signal.
## Configuration
The tool reads project settings from `project.toml`.
Non-goal: environment-variable configuration is intentionally omitted for now. Add it when there is
a concrete non-interactive deployment path that cannot write a project config file.
References
| Source | Use | Note |
|---|---|---|
| Diátaxis explanation context | supports |
Explanation is where design reasons and alternatives belong. |