architectural-proposals

name	architectural-proposals
description	Write evidence-based architectural proposals before implementation
domain	architecture, planning
confidence	high
source	template

Context

Use this skill when a change needs alignment before code is written: new subsystems, major refactors, significant dependency choices, or changes that affect multiple areas of the project.

Patterns

Proposal structure

A strong proposal usually includes:

1. Problem statement — what is not working today, with concrete evidence
2. Proposed approach — the design, boundaries, and key technical choices
3. Impact — what changes, what stays the same, and who is affected
4. Risks and mitigations — likely failure modes and how to reduce them
5. Scope — what is included now and what is intentionally deferred
6. Open questions — decisions that still need input

Writing rules

• Ground claims in repo context, requirements, and observable constraints
• Prefer specific file paths, interfaces, data flows, and rollout steps over vague language
• Acknowledge trade-offs; do not present any option as perfect
• Separate facts, assumptions, and recommendations clearly

Decision framing

For each major choice, capture:

• Recommendation
• Alternatives considered
• Why the recommendation wins
• What validation is still needed

Risk documentation

For each important risk, record:

• Risk — specific failure mode
• Likelihood — low / medium / high
• Impact — low / medium / high
• Mitigation — concrete action to reduce risk

Examples

✓ Good:

• Documenting why a static JSON catalog is sufficient now and when a database would be needed later
• Comparing two hosting approaches and naming the operational trade-offs
• Explaining how a refactor preserves current behavior while changing internal structure

✗ Poor:

• "We can figure out the details later"
• "This will scale forever" without evidence
• Listing tasks without describing the underlying design

Anti-patterns

• Writing proposals with no evidence from the current codebase
• Hiding trade-offs to make a recommendation sound easier
• Mixing implementation details with unresolved product questions
• Starting major implementation work before the core decision is documented