architectural-proposals

Structure the proposal with a problem statement citing specific evidence, a technically specific proposed architecture, impact analysis on existing work, explicit key decisions with recommendations, risks with mitigations, and a bounded v1 scope. Read existing decisions and architecture docs first.

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 an appendix of alternatives considered.

Acknowledge the shift explicitly by renumbering affected waves, cascade impacts to downstream milestones, identify work that can proceed in parallel, and document new blocking dependencies. Always preserve backward compatibility for existing functionality.

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

Common anti-patterns include solution-first thinking without a problem statement, vague architecture without technical specifics, ignoring impact on existing work, missing risk analysis, unbounded scope, and unsubstantiated claims without evidence.