architectural-proposals

Document architectural concerns by producing comprehensive proposals that outline problem statements, proposed architecture, risks, and required decisions. This creates team alignment before code is written, making it cheaper to change a doc than refactor code later.

Write an architectural proposal when architecture shifts invalidate existing assumptions, product direction changes require a new foundation, multiple milestones are affected by a decision, or external dependencies like SDK APIs change.

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

Frame technical decisions by providing a clear recommendation alongside alternatives, citing evidence and specific API paths for rationale, acknowledging trade-offs, and defining required sign-offs and ownership to secure consensus.

Manage foundation shifts by acknowledging the change, cascading impacts across affected waves, preserving parallel work where possible, and updating dependencies within the proposal to maintain alignment.

Document risks by detailing concrete mitigations for each identified concern within the proposal. This ensures teams acknowledge trade-offs and have specific strategies to handle potential failures during implementation.