← Development guidelines

Code · Architecture · UX

Architecture and UX change plan template

Download editable Markdown

Template edition: 3.2.0

Revised: 2026-10-25

Guideline content by Lucas Vitti, licensed under CC BY 4.0. See scope and attribution.

Save a plan in the project's dedicated documentation folder, normally docs/plans/<version-or-change-id>.md. Provide the document before implementation and obtain explicit approval for its identifiable revision and scope. For a small change, keep it short and explain unaffected architecture or UX areas. Do not fill sections with invented requirements. Link the current project design guide and use the version journal template to record the full technical outcome, paired with the user changelog template for what changes for users.

Identity and scope

Architecture plan

Internal parameters and product constraints

Apply DOC-09 before implementation. Link the canonical register, normally docs/parameters.md, using the parameter record in the project design guide template. Include every planned internal behavior/policy parameter in new work and inspect every existing parameter affecting the change, even when its value will remain fixed. Explain each in ordinary language before giving its internal name.

No parameter changes is a valid conclusion only after the relevant values have been inventoried. Do not replace this section with "defaults apply," assume an internal constant is a user setting, or make every value configurable merely to complete the template. For a documentation-only change, identify relevant build/check parameters and explain why application runtime values are unaffected. Keep secrets as references, never literal values.

UX plan

Verification and delivery plan

Approval record

Keep this pending until explicit approval exists. Existing approval covering the same plan and scope remains valid; do not add repeated approvals for unchanged work. Plan approval alone does not authorize deployment. Preserve the approved revision; record later clarifications or replacements explicitly.

Pre-deployment review

Present the actual outcome, applicable checks, limitations, both changelogs, and deployment target. Confirm the implemented scope matches the approved plan and deployment authorization covers the release and target. If it does not, obtain the missing authorization before deployment. Record the actual publication result in the journal, including a failure or partial rollout; passing checks alone is not evidence of deployment.