architectural-proposals

Name: architectural-proposals
Availability: InStock
Author: sudhakrms

Document alignment gaps and architectural concerns in structured proposals.

1|Updated Apr 17, 2026

Search Tags:#documentation #alignment #risk-management #decision-making #team-collaboration #architectural-proposals #product-direction

Ready to run

npx skills add https://github.com/sudhakrms/CalendarControl --skill architectural-proposals-sudhakrms

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:

Architecture shifts invalidate existing assumptions
Product direction changes require new foundation
Multiple waves/milestones will be affected by a decision
External dependencies (Copilot CLI, SDK APIs) change

Core Features & Use Cases

Proposal Structure (docs/proposals/): Required sections include Problem Statement, Proposed Architecture, What Changes, What Stays the Same, Key Decisions Needed, Risks and Mitigations, Scope; Optional sections include Implementation Plan, Success Criteria, Open Questions, Appendix.
Tone Ceiling Enforcement: Always cite evidence, justify recommendations with rationale, acknowledge trade-offs, be specific about APIs, file paths.
Wave Restructuring Pattern: If foundation shifts, acknowledge, cascade impacts, preserve parallel work, update dependencies.
Decision Framing: Provide a clear recommendation with alternatives, rationale, and required sign-offs.
Risk Documentation: Document risks with concrete mitigations.
Examples illustrate how to frame decisions and preserve backward compatibility.

Quick Start

Review current directives and architecture, then draft a structured architectural proposal in docs/proposals/ following the required sections.

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 concerns before implementation begins?▼

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.

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, multiple milestones are affected by a decision, or external dependencies like SDK APIs change.

What sections should be included in an architectural proposal?▼

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.

How do I frame technical decisions for team sign-off?▼

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.

How do I manage foundation shifts that affect parallel development waves?▼

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.

What is the best way to document risks in architectural proposals?▼

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.