Code · Architecture · UX
Architecture and UX change plan template
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
- Project and intended version: [project, preceding version, intended version, and adopted guideline edition].
- Plan identity: [stable ID, revision or content hash, date, author, and decision authority].
- Status: [draft, awaiting approval, approved, superseded; implementation and deployment states tracked separately].
- Problem and intended outcome: [current behavior, proposed behavior, user benefit, and evidence].
- Scope and exclusions: [requested work, affected features, and boundaries of authorization].
- Existing records: [current design guide, relevant page/form records, decisions, known debt, and starter provenance if used].
Architecture plan
- Responsibilities and source map: [modules to reuse, add, or change and why each responsibility belongs there].
- Boundary contracts: [public operations, inputs, result/failure shapes, state/data owners, permitted writers, side effects, and cleanup lifetimes; link canonical definitions].
- Dependency policy: [allowed and prohibited dependencies, private internals, narrow injected capabilities, and assembly point].
- External details: [adapters justified by testing, failure handling, or expected change; provider differences and guarantees preserved].
- Security and compatibility: [authorization, trust boundaries, contracts, transaction integrity, migration needs, and affected clients].
- Baseline and isolation: [working reference feature, dependency checks, realistic change scenario or substitute, and real-adapter verification].
- Alternatives and tradeoffs: [consequential choices, reasons, and linked decisions; existing debt outside scope].
- Unaffected areas: [architecture impact is none only with an explanation grounded in the change].
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.
- Register and coverage: [document location, source revision, reviewed directories/layers, discovery and manual-review method, exclusions, legacy gaps, owner, and next review scope].
- Current and proposed values: [parameter IDs, exact value and unit, scope, source location, default versus observed effective value, and proposed changes; unknown values explicitly pending verification].
- Policy and change decisions: [why each value exists, user effect, should it remain fixed or be configurable, allowed range, owner/approval, alternatives, compatibility and cost/resource/security impact].
- Enforcement and dependencies: [validation and failure behavior, frontend/backend/worker/proxy limits, overrides and precedence, restart or redeploy needs; effective behavior may be constrained by another layer].
- Verification and documentation: [below/at/above-limit cases where applicable, configuration fallback and invalid/override cases, runtime confirmation, register and version-journal updates].
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
- Affected pages and forms: [stable IDs, routes/screens, user and permission scope].
- Main intent and success: [one primary objective for each affected page/form and observable success condition].
- Task arrangement: [primary content, supporting controls, secondary task destinations, navigation and scroll ownership, and how competing nested interaction layers are avoided].
- States and recovery: [loading, empty, no-match, error, success, unsaved changes, cancellation, and return behavior as applicable].
- Accessibility and layout: [keyboard/focus behavior, labels, narrow screens, long content, and concrete visual hierarchy choices].
- Acceptance criteria: [observable outcomes and checks linked to relevant UX/VIS rules].
- Unaffected areas: [why no page or interaction changes when the work has no UX impact].
Verification and delivery plan
- Behavior preservation or intended change: [before/after scenarios, important contracts, authorization and failure paths].
- Commands and environment: [required checks and safe disposable fixtures; no production credentials or data in this document].
- Structural checks: [size review and exceptions, dependency-check scope and negative fixture, runtime coupling review].
- UX checks: [interaction, keyboard, viewport, and content cases; justified not-applicable cases].
- Planned release and target: [version, artifact identity method, destination, rollout, migrations, recovery or rollback].
- Technical journal: [path of the draft full entry; actual changes, evidence, and deployment state added after implementation].
- User changelog: [path of the matching version entry; practical changes, moved/removed controls or pages, fixes, user actions, affected audience, and actual availability; explicitly state no user-visible changes when applicable].
- Reconciliation: [confirm both records agree on version, dates, facts, and availability; preserve earlier entries].
Approval record
- Plan revision and scope approved: [exact revision/hash and any conditions].
- Approver and date: [actual user or designated authority and date].
- Approval evidence: [message or decision reference with enough context to establish authorization; no invented approval].
- Implementation authorization: [scope and constraints covered by that approval].
- Deployment authorization: [whether the same approval explicitly covers this release and target; otherwise pending].
- Material revisions: [what changed, replacement plan revision, and renewed approval before affected implementation].
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.