architectural-proposals

Start with a problem statement citing specific evidence, then describe the proposed architecture with technical specifics. Document what changes and what stays the same, frame key decisions with recommendations, list risks with mitigations, and define explicit v1 scope.

Required sections are problem statement, proposed architecture, what changes, what stays the same, key decisions needed, risks and mitigations, and scope. Optional sections include implementation plan, success criteria, open questions, and appendix.

Frame each decision as a recommendation with alternatives considered, decision rationale explaining why the recommended option wins, and explicit sign-off requirements naming which roles must approve. Always acknowledge trade-offs rather than claiming perfect solutions.

Write a proposal when architecture shifts invalidate existing assumptions, product direction changes require new foundations, multiple milestones are affected, or external dependencies change. Changing a document is cheaper than refactoring code.

Common anti-patterns include solution-first thinking without problem statements, vague architecture descriptions, ignoring impact on existing milestones, missing risk analysis, unbounded scope, and unsubstantiated claims without evidence.