architectural-proposals

Document architectural decisions with structured, evidence-backed proposal templates.

49|6|Updated Aug 24, 2021

Search Tags:#architecture #documentation #alignment #proposal #decision-making #risk-analysis #wave-management

Ready to run

npx skills add https://github.com/webmaxru/bpm-counter --skill architectural-proposals-webmaxru

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: architectural-proposals
Source: https://github.com/webmaxru/bpm-counter/tree/main/.copilot/skills/architectural-proposals
Command: npx skills add https://github.com/webmaxru/bpm-counter --skill architectural-proposals-webmaxru

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Proposals create alignment before code is written. Cheaper to change a doc than refactor code.

Core Features & Use Cases

Structured proposal template in docs/proposals/ with required sections (Problem Statement, Proposed Architecture, What Changes, What Stays the Same, Key Decisions Needed, Risks and Mitigations, Scope).
Optional sections for Implementation Plan, Success Criteria, Open Questions, Appendix.
Guidance on tone, risk analysis, and wave impact to ensure traceability and governance.

Quick Start

Create a proposal in docs/proposals/ with the required sections and a clear decision outcome.

Frequently Asked Questions about architectural-proposals

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I document architectural decisions to align teams before coding?▼

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.

What should be included in an architectural proposal template?▼

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.

When do I need to write an architectural proposal?▼

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.

How do I define scope for architectural changes across multiple teams?▼

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.

What is the best way to perform risk analysis for software architecture proposals?▼

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.