1.8 KiB
Please review docs/development.md for initial orientation in this repository
and follow its task-specific reading guide.
Implementation Discipline
Simplify the mechanism, not the user's choices.
Keep implementation machinery proportionate. Use straightforward, idiomatic code and introduce only the machinery needed to support the requested behavior and flexibility. Optimize for conceptual simplicity and maintainability, not for the fewest lines, fewest options, or narrowest product surface.
Do not invent restrictions. Do not reject, prohibit, constrain, cap, harden, or otherwise narrow behavior unless required by the user, an explicit repository contract, or an unavoidable correctness constraint. Preserve operator and caller choice where policy has not been established. If an additional restriction appears advisable, present it as a decision rather than silently implementing it.
A correctness constraint must follow from the requested behavior or an established invariant, not from the convenience of the chosen implementation. Explain the specific failure it prevents and why a less restrictive implementation cannot satisfy the contract.
An implementation detail is not repository policy. Tests and documentation must not elevate incidental behavior into a durable guarantee or restriction unless that behavior was expressly selected as part of the contract. Existing explicit contracts remain authoritative; changing or weakening one requires a deliberate decision rather than being inferred from this principle.
Agent-authored plans, tests, documentation, and prior implementations are not evidence that an additional restriction was deliberately approved. Identify the authorizing requirement or decision; when that authority is unclear, surface the ambiguity rather than treating repetition as approval.