architectural-proposals

Document architectural decisions by creating structured proposals that detail problem statements, proposed architecture, changes, scope, risks, and decisions. Store these documents under docs/proposals with explicit ownership to ensure frontmatter includes name and description.

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

Required sections in an architectural proposal include Problem Statement, Proposed Architecture, What Changes, What Stays the Same, Key Decisions Needed, Risks and Mitigations, and Scope, ensuring structured documentation with explicit ownership.

Reduce rework during a software rewrite by creating structured architecture proposals before implementation. Proposals create alignment before code is written, making it cheaper to change a document than to refactor code later.

Manage risk and stakeholder alignment by documenting proposed architecture changes, risks and mitigations, and key decisions needed in a structured proposal before implementation begins, ensuring all stakeholders are aligned on product direction changes.

Yes, use architecture proposals when external dependencies such as Copilot CLI or SDK APIs change. Documenting the problem statement, proposed architecture, and scope ensures alignment across multiple affected waves or milestones.