architectural-proposals

Document architectural decisions using structured proposals with required sections like Problem Statement, Proposed Architecture, and Key Decisions Needed. This creates cross-team alignment before implementation, making it cheaper to change a doc than refactor code.

An architectural proposal template must include Problem Statement, Proposed Architecture, What Changes, What Stays the Same, Key Decisions Needed, Risks and Mitigations, and Scope sections. Optional sections cover Implementation Plan, Success Criteria, and Open Questions.

Write an architectural proposal when architecture shifts invalidate existing assumptions, product direction changes require a new foundation, or cross-team dependencies require alignment. It ensures explicit decision documentation and traceability before work begins.

Define scope for architectural changes by explicitly separating what is included in v1 versus what is deferred. This structured scoping within the proposal guides work, manages wave impact, and ensures cross-team dependencies are properly aligned.

The best way to perform risk analysis for software architecture proposals is using a structured template with a dedicated Risks and Mitigations section. This ensures evidence-backed decision-making, governance, and traceability for wave impact.